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The information contained in this document is subject to change without 
notice. 

Agilent Technologies shall not be liable for any errors contained in this 
document. Agilent Technologies makes no warranties of any kind with 
regard to this document, whether express or implied. Agilent Technologies 
specifically disclaims the implied warranties of merchantability and fitness 
for a particular purpose. Agilent Technologies shall not be liable for any 
direct, indirect, special, incidental, or consequential damages, whether 
based on contract, tort, or any other legal theory, in connection with the 
furnishing of this document or the use of the information in this document. 

Warranty Information 

A copy of the specific warranty terms applicable to your Agilent Technologies 
product and replacement parts can be obtained from Agilent Technologies, 
Inc. 

U.S. Government Restricted Rights 

The Software and Documentation have been developed entirely at private 
expense. They are delivered and licensed as "commercial computer 
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7015 (May 1991) or DFARS 252.227-7014 (Jun 1995), as a "commercial 
item" as defined in FAR 2.101(a), or as "Restricted computer software" as 
defined in FAR 52.227-19 (Jun 1987) (or any equivalent agency regulation 
or contract clause), whichever is applicable. You have only those rights 
provided for such Software and Documentation by the applicable FAR or 
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Introduction 


This Agilent Technologies VISA User’s Guide describes the Agilent Virtual 
Instrument Software Architecture (VISA) library and shows how to use it to 
develop instrument drivers and I/O applications on Windows 95, Windows 
98, Windows Me, Windows NT 4.0, and Windows 2000, and on HP-UX 
version 10.20. This chapter includes: 

■ What’s in This Guide? 

■ VISA Overview 


NOTE 

Before you can use VISA, you must install and configure VISA on your 
computer. See Agilent 10 Libraries Installation and Configuration Guide 
for Windows for installation on Windows systems. See Agilent 10 
Libraries Installation and Configuration for HP-UX for installation on 
HP-UX systems. 

This guide shows programming techniques using C/C++ and Visual 
Basic. Since VISA and SICL are different libraries, using VISA functions 
and SICL functions in the same I/O application is not supported. Unless 
indicated, Windows NT refers to Windows NT 4.0. 
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Introduction 

What’s in This Guide? 


What’s in This Guide? 

■ Chapter 1 - Introduction describes the contents of this guide, 
provides an overview of VISA, and shows how to contact Agilent 
Technologies. 

■ Chapter 2 - Building a VISA Application in Windows describes how 
to build a VISA application in a Windows environment. An example 
program is provided to help you get started programming with VISA. 

■ Chapter 3 - Building a VISA Application in HP-UX describes how to 
build a VISA application in the HP-UX environment. An example 
program is provided to help you get started programming with VISA. 

■ Chapter 4 - Programming with VISA describes the basics of VISA 
and lists some example programs. The chapter also includes 
information on creating sessions, using formatted I/O, events, etc. 

■ Chapter 5 - Programming via GPIB and VXI gives guidelines to use 
VISA to communicate over the GPIB, GPIB-VXI, and VXI interfaces 
to instruments. 

■ Chapter 6 - Programming via LAN gives guidelines to use VISA to 
communicate over a LAN (Local Area Network) to instruments. 

■ Chapter 7 - VISA Language Reference provides an alphabetical 
reference of supported VISA functions. 

■ Appendix A - VISA Library Information lists VISA data types and 
their definitions, VISA error codes, and VISA directory information. 

■ Appendix B - VISA Resource Classes describes the six VISA 
Resource Classes, including attributes, events, and operations. 

■ Glossary includes a glossary of terms and their definitions. 
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VISA Overview 


VISA Overview 

VISA is a part of the Agilent 10 Libraries. The Agilent 10 Libraries consists 
of two libraries: Agilent Virtual Instrument Software Architecture (VISA) and 
Agilent Standard Instrument Control Library (SICL). This guide describes 
VISA for supported Windows and HP-UX environments. 

For information on using SICL in Windows, see the Agilent SICL User’s 
Guide for Windows. For information on using SICL in HP-UX, see the 
Agilent Standard Instrument Control Library User’s Guide for HP-UX. For 
information on the Agilent 10 Libraries, see the Agilent 10 Libraries 
Installation and Configuration Guide. 

Using VISA and SICL 

Agilent Virtual Instrument Software Architecture (VISA) is an 10 library 
designed according to the \IX\plug&play System Alliance that allows 
software developed from different vendors to run on the same system. 

Use VISA if you want to use \IX\plug&play instrument drivers in your 
applications, or if you want the I/O applications or instrument drivers that 
you develop to be compliant with VX\plug&play standards. If you are using 
new instruments or are developing new I/O applications or instrument 
drivers, we recommend you use Agilent VISA. 

Agilent Standard Instrument Control Library (SICL) is an I/O library 
developed by Agilent that is portable across many I/O interfaces and 
systems. You can use Agilent SICL if you have been using SICL and 
want to remain compatible with software currently implemented in SICL. 
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VISA Overview 


VISA Support on 
Windows 


VISA Support on 
HP-UX 


VISA Users 


VISA Support 

Agilent VISA is an I/O library that can be used to develop I/O applications 
and instrument drivers that comply with the \IX\plug&play standards. 
Applications and instrument drivers developed with VISA can execute on 
\/X\plug&play system frameworks that have the VISA I/O layer. Therefore, 
software from different vendors can be used together on the same system. 


This 32-bit version of VISA is supported on Windows 95, Windows 98, 
Windows Me, Windows NT, and Windows 2000. (Support for the 16-bit 
version of VISA was removed in version H.01.00 of the Agilent 10 Libraries.) 
C, C++, and Visual Basic are supported on all these Windows versions. 

For Windows, VISA is supported on the GPIB, VXI, GPIB-VXI, Serial 
(RS-232), and LAN interfaces. VISA for the VXI interface on Windows NT 
is shipped with the Agilent Embedded VXI Controller product only. LAN 
support from within VISA occurs via an address translation such that a 
GPIB interface can be accessed remotely over a computer network 


VISA is supported on the GPIB, VXI, GPIB-VXI, and LAN interfaces on 
HP-UX version 10.20. LAN support from within VISA occurs via an address 
translation such that a GPIB interface can be accessed remotely over a 
computer network 


VISA has two specific types of users. The first type is the instrumentation 
end user who wants to use \IX\plug&play instrument drivers in his or her 
applications. The second type of user is the instrument driver or I/O 
application developer who wants to be compliant with \IX\plug&play 
standards. 

Software development using VISA is intended for instrument I/O and 
C/C++ or Visual Basic programmers who are familiar with the Windows 95, 
Windows 98, Windows Me, Windows 2000, Windows NT, or HP-UX 
environment. To perform VISA installation and configuration on Windows NT 
or HP-UX, you must have system administration privileges on the Windows 
NT system or super-user (root) privileges on the HP-UX system. 
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VISA Overview 


VISA Documentation 

This table shows associated documentation you can use when programming 
with Agilent VISA in the Windows or HP-UX environment. 


Agilent VISA Documentation 


Document 

Description 

Agilent IO Libraries Installation and 
Configuration Guide for Windows 

Shows how to install, configure, and maintain the Agilent IO 
Libraries on Windows. 

Agilent IO Libraries Installation and 
Configuration Guide for HP-UX 

Shows how to install, configure, and maintain the Agilent IO 
Libraries on HP-UX. 

VISA Online Help 

Information is provided in the form of Windows Help. 

VISA Example Programs 

Example programs are provided online to help you develop 

VISA applications. 

\/X\plug&play System Alliance VISA 
Library Specification 4.3 

Specifications for VISA. 

IEEE Standard Codes, Formats, 
Protocols, and Common Commands 

ANSI/IEEE Standard 488.2-1992. 

VXIbus Consortium specifications 
(when using VISA over LAN) 

TCP/IP Instrument Protocol Specification - VXI-11, Rev. 1.0 
TCP/IP-VXIbus Interface Specification - VXI-11.1, Rev. 1.0 
TCP/IP-IEEE 488.1 Interface Specification - VXI-11.2, Rev. 1.0 
TCP/IP-IEEE 488.2 Instrument Interface Specification - VXI-11.3, 
Rev. 1.0 


Contacting Agilent 

■ In the USA and Canada, you can reach Agilent Technologies at 
these telephone numbers: 

USA: 1-800-452-4844 
Canada: 1-877-894-4414 

■ Outside the USA and Canada, contact your country’s Agilent support 
organization. A list of contact information for other countries is 
available on the Agilent web site: 

http://www.agilent.com/find/assist 
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Building a VISA Application in Windows 


This chapter gives guidelines to build a VISA application in a Windows 
environment. The chapter contains the following sections: 

■ Building a VISA Program (C/C++) 

■ Building a VISA Program (Visual Basic) 

■ Logging Error Messages 
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Building a VISA Application in Windows 

Building a VISA Program (C/C++) 


Linking to VISA 
Libraries 


Microsoft Visual 
C++ Version 6.0 
Compilers 


Building a VISA Program (C/C++) 

This section gives guidelines to build VISA programs using C/C++ language, 
including: 

■ Compiling and Linking VISA Programs (C/C++) 

■ Example VISA Program (C/C++) 

Compiling and Linking VISA Programs (C/C++) 

This section provides a summary of important compiler-specific 
considerations for several C/C++ compiler products when developing Win32 
applications. 


Your application must link to one of the VISA import libraries as follows, 
assuming default installation directories. 

■ VISA on Windows 95, Windows 98, or Windows Me: 

C:\Program Files\VISA\WIN95\LIB\MSC\VISA32.LIB 
(Microsoft compilers) 

C:\Program Files\VISA\WIN95\LIB\BC\VISA32.LIB 
(Borland compilers) 

■ VISA on Windows NT or Windows 2000: 

C:\Program Files\VISA\WINNT\LIB\MSC\VISA32.LIB 
(Microsoft compilers) 

C:\Program Files\VISA\WINNT\LIB\BC\VISA32.LIB 
(Borland compilers) 

1 Select Pro ject | Update All Dependencies from the menu. 

2 Select Project | Settings from the menu and click the 
C/C++ button. 

3 Select Code Generation from the Category list box and 
select Multi-Threaded using DLL from the Use Run-Time 
Libraries list box. (VISA requires these definitions for Win32.) 
Click ok to close the dialog boxes. 
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Building a VISA Application in Windows 

Building a VISA Program (C/C++) 


Borland C++ 
Version 4.0 
Compilers 


4 Select Project | Settings from the menu. Click the Link 
button and add visa32.lib to the Object/Library Modules list 
box. Optionally, you may add the library directly to your project file. 
Click ok to close the dialog boxes. 

5 You may want to add the include file and library file search paths. 
They are set by: 

□ Select Tools | Options from the menu. 

□ Click the Directories button to set the include file path. 

□ Select Include Files from the Show Directories For 
list box. 

□ Click the Add button and type one of the following: 
C:\Program Files\VISA\WIN95\INCLUDE OR 
C:\Program Files\VISA\WINNT\INCLUDE. 

6 Select Library Files from the Show Directories For 
list box. 

7 Click the Add button and type one of the following: 

C:\Program Files\VISA\WIN95\LIB\MSC OR 

C:\Program Files\VISA\WINNT\LIB\MSC 


You may want to add the include file and library file search paths. They 
are set under the Options | Project menu selection. Double-click 
Directories from the Topics list box and add one of the following: 

C:\Program Files\VISA\WIN95\INCLUDE 
C:\Program Files\VISA\WIN95\LIB\BC 

OR 

C:\Program Files\VISA\WINNT\INCLUDE 
C:\Program Files\VISA\WINNT\LIB\BC 
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Example C/C++ 
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Code 


Example VISA Program (C/C++) 

This section lists an example program called idn that queries a GPIB 
instrument for its identification string. This example assumes a Win32 
Console Application using Microsoft or Borland C/C++ compilers on 
Windows. 

■ For VISA on Windows 95, Windows 98, and Windows Me, the idn 
example files are in \Program Files\VISA\WIN95\AGVISA\SAMPLES. 

■ For VISA on Windows NT or Windows 2000, the idn example files 
are in \Program Files\VISA\WINNT\AGVISA\SAMPLES. 

The source file idn . c follows. An explanation of the various function calls in 
the example is provided directly after the program listing. If the program runs 
correctly, the following is an example of the output if connected to a 54601A 
oscilloscope. If the program does not run, see the Event Viewer for a list 
of run-time errors. 

HEWLETT-PACKARD,54601A,0,1.7 

/*idn.c 

This example program queries a GPIB device for an 
identification string and prints the results. Note 
that you must change the address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
char buf [256] = {0}; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM(&defaultRM); 

viOpen (defaultRM, "GPIB0 : : 22 : : INSTR" , VI_NULL, VI_NULL, 
&vi) ; 

/* Initialize device */ 
viPrintf(vi, "*RST\n"); 

/* Send an *IDN? string to the device */ 
viPrintf(vi, "*IDN?\n"); 
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Building a VISA Program (C/C++) 


/* Read results */ 
viScanf(vi, "%t", buf); 

/* Print results */ 

printf("Instrument identification string: %s\n", buf) ; 

/* Close session */ 
viClose(vi); 
viClose(defaultRM);} 


Example C/C++ A summary of the VISA function calls used in the example C/C++ program 

Program Contents follows. For a more detailed explanation of VISA functionality, see Chapter 

4 - Programming With VISA. See Chapter 7 - VISA Language Reference for 
more detailed information on these VISA function calls. 


Function(s) 

Description 

visa.h 

This file is included at the beginning of the file to provide the function 
prototypes and constants defined by VISA. 

ViSession 

The ViSession is a VISA data type. Each object that will establish a 
communication channel must be defined as ViSession. 

viOpenDefaultRM 

You must first open a session with the default resource manager with the 
viOpenDefaultRM function. This function will initialize the default 
resource manager and return a pointer to that resource manager session. 

viOpen 

This function establishes a communication channel with the device 
specified. A session identifier that can be used with other VISA functions 
is returned. This call must be made for each device you will be using. 

viPrintf and 
viScanf 

These are the VISA formatted I/O functions that are patterned after those 
used in the C programming language. The viPrintf call sends the 

IEEE 488.2 *rst command to the instrument and puts it in a known state. 
The viPrintf call is used again to query for the device identification 
(*idn?). The viScanf call is then used to read the results. 

viClose 

This function must be used to close each session. When you close a 
device session, all data structures that had been allocated for the session 
will be deallocated. When you close the default manager session, all 
sessions opened using that default manager session will be closed. 
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a Visual Basic VISA 
Program 
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Building a VISA Program (Visual Basic) 

This section gives guidelines to build a VISA program in the Visual Basic 
language, including: 

■ Visual Basic Programming Considerations 

■ Example VISA Program (Visual Basic) 

Visual Basic Programming Considerations 

Some considerations for programming in Visual Basic follow. 


Before you can use VISA specific functions, your application must add the 
visa32.bas VISA Visual Basic module found in one of the following 
directories (assuming default installation directories). For Windows 2000/NT, 
C:\Program Files\VISA\winnt\include\. For Windows 95/98/Me, 

C:\Program Files\VISA\winnt\include\. 

To install visa32.bas\ 

1 Select Project | Add Module from the menu 

2 Select the Existing tab 

3 Browse and select the visa32.bas file from applicable directory 

4 Click the Open button 


VISA functions return a status code which indicates success or failure of the 
function. The only indication of an error is the value of returned status code. 
The VB Error variable is not set by any VISA function. Thus, you cannot use 
the 'ON ERROR' construct in VB or the value of the VB Error variable to 
catch VISA function errors. 

VISA cannot callback to a VB function. Thus, you can only use the 
VI_QUEUE mechanism in viEnableEvent. There is no way to install a 
VISA event handler in VB. 

VISA functions that take a variable number of parameters (viPrintf, 
viScanf, viQueryf ) are not callable from VB. Use the corresponding 
viVPrintf, viVScanf and viVQueryf functions instead. 

You cannot pass variables of type Variant to VISA functions. If you attempt 
this, the Visual Basic program will probably crash with a 'General Protection 
Fault' or an 'Access Violation'. 
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Commands 


Numeric Arrays 


Strings 


Building a VISA Application in Windows 

Building a VISA Program (Visual Basic) 


The functions viVPrintf, viVscanf and viVqueryf can be called 
from VB, but there are restrictions on the format conversions that can be 
used. Only one format conversion command can be specified in a format 
string (a format conversion command begins with the % character). 

For example, the following is invalid: 

status = viVPrintf(vi, "%lf%d" + Chr$(10), ...) 

Instead, you must make one call for each format conversion command, as 
shown in the following example: 

status = viVPrintf(vi, "%lf" + Chr$(10), dbl value) 
status = viVPrintf(vi, "%d" + Chr$(10), int value) 

When reading to or writing from a numeric array, you must specify the first 
element of a numeric array as the params parameter. This passes the 
address of the first array element to the function. For example, the following 
code declares an array of 50 floating point numbers and then calls 
viVPrintf to write from the array. 

Dim fit array(50) As Double 

status = viVPrintf(id, "%,50f", dbl_array(0)) 

When reading in a string value with viVScanf or viVQueryf, you must 
pass a fixed length string as the params parameter. To declare a fixed 
length string, instead of using the normal variable length declaration: 

Dim strVal as String 

use the following declaration, where 40 is the fixed length. 

Dim strVal as String * 40 
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Steps to Run the 
Program 


Example VISA Program (Visual Basic) 

This section lists an example program called idn that queries a GPIB 
instrument for its identification string. This example builds a Standard EXE 
application for WIN32 programs using the Visual Basic 6.0 programming 
language. 

For VISA on Windows 95, Windows 98, or Windows Me, the idn example 
files are in C:\Program Files\VISA\WIN95\AGVISA\SAMPLES\ vb\idn. 

For VISA on Windows NT or Windows 2000, the idn example files are in 
C:\Program Files\VISA\WINNT\AGVISA\SAMPLES\vb\idn. 


The steps to build and run the idn example program follow. 

1 Connect an instrument to a GPIB interface that is compatible with 
IEEE 488.2. 

2 Start the Visual Basic 6.0 application. 


NOTE 

This example assumes you are building a new project (no .vbp file exists 
for project). If you do not want to build the project from scratch, from the 
menu select File | Open Project. . . and select and open the 
idn. vbp file and skip to Step 9. 


3 Start a new Visual Basic Standard EXE project. VB 6.0 will open 
a new Projectl project with a blank Form, Forml. 

4 From the menu, select Project | Add Module, select the 
Existing tab, and browse to the idn directory. 

5 The idn example files are located in directory vb\samples\idn. 
Select the file idn.bas and click Open. Since the Main() subroutine 
is executed when the program is run without requiring user 
interaction with a Form, Forml may be deleted if desired. To do 
this, right-click Forml in the Project Explorer window and select 
Remove Forml. 

6 VISA applications in Visual Basic require the VISA Visual Basic 
(VB) declaration file visa32.bas in your VB project. This file 
contains the VISA function definitions and constant declarations 
needed to make VISA calls from Visual Basic. 
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Building a VISA Program (Visual Basic) 


7 To add this module to your project in VB 6.0, from the menu select 
Project | Add Module, select the Existing tab, browse to 
the directory containing the VB Declaration file, select visa32.bas, 
and click Open. 

8 The name and location of the VB declaration file depends on which 
operating system is used. Assuming the 'standard' VISA directory 
C:\Program Files\Visa or the 'standard' VXIpnp directory 
C:\VXIpnp, the visa32.bas file can be located in one of these 
directories: 

\winnt\include\visa32.bas (Windows NT/2000) 
\win95\include\visa32.bas (Windows 95/98/Me) 

9 At this point, the Visual Basic project can be run and debugged. 
You will need to change the VISA Interface Name and address in 
the code to match your device’s configuration. 

10 If you want to compile to an executable file, from the menu select 
File | Make idn. exe ... and press Open. This will create 
idn.exe in the idn directory. 


Example Program An explanation of the various function calls in the example is provided after 

Source Code the program listing. If the program runs correctly, the following is an example 

of the output in a Message Box if connected to a 54601A oscilloscope. 

HEWLETT-PACKARD,54601A,0,1.7 

If the program does not run, see the Event Viewer for a list of run-time 
errors. The source file idn.bas follows. 

Option Explicit 

I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I 

' idn.bas 

' This example program queries a GPIB device for an identification 
' string and prints the results. Note that you may have to change the 
' VISA Interface Name and address for your device from "GPIBO" and "22", 
' respectively. 

I I I I I I I I I I ! I I I I I I I I I I I I I I I I I ! I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I I 

Sub Main() 

Dim defrm As Long 'Session to Default Resource Manager 

Dim vi As Long 'Session to instrument 

Dim strRes As String * 200 'Fixed length string to hold results 
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' Open the default resource manager session 
Call viOpenDefaultRM(defrm) 

' Open the session to the resource 

' The "GPIBO" parameter is the VISA Interface name to a GPIB 
' instrument as defined in 

' Start | Programs | Agilent 10 Libraries | 10 Config 

' Change this name to what you have defined your VISA Interface. 
' "GPIBO::22::INSTR" is the address string for the device. 

' this address will be the same as seen in: 

' Start | Programs | Agilent 10 Libraries | VISA Assistant 
' after the VISA Interface Name is defined in 10 Config) 

Call viOpen(defrm, "GPIBO::22::INSTR", 0, 0, vi) 

' Initialize device 

Call viVPrintf(vi, "*RST" + Chr$(10), 0) 


' Ask for the device's *IDN string. 

Call viVPrintf(vi, "*IDN?" + Chr$(10), 0) 

' Read the results as a string. 

Call viVScanf(vi, "%t", strRes) 

' Display the results 

MsgBox "Result is: " + strRes, vbOKOnly, "*IDN? Result" 

' Close the vi session and the resource manager session 
Call viClose(vi) 

Call viClose(defrm) 

End Sub 
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Example Program A summary of the VISA function calls used in the example Visual Basic 
Contents program follows. For a more detailed explanation of VISA functionality, see 

Chapter 4 - Programming with VISA. See Chapter 7 - VISA Language 
Reference for more detailed information on these VISA function calls. 


Function(s) 

Description 

viOpenDefaultRM 

You must first open a session with the default resource manager with the 
viOpenDefaultRM function. This function will initialize the default 
resource manager and return a pointer (defrm) to that resource manager 
session. 

viOpen 

This function establishes a communication channel with the device 
specified. A session identifier (vi) that can be used with other VISA 
functions is returned. This call must be made for each device you will be 
using. 

viVPrintf and 

viVScanf 

These are the VISA formatted I/O functions. The viVPrintf call sends 
the IEEE 488.2 *rst command to the instrument (plus a linefeed 
character) and puts it in a known state. The viVPrintf call is used again 
to query for the device identification (*idn?). The viVScanf call is then 
used to read the results (strRes) that are displayed in a Message Box. 

viClose 

This function must be used to close each session. When you close a 
device session, all data structures that had been allocated for the session 
will be deallocated. When you close the default manager session, all 
sessions opened using that default manager session will be closed. 
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Logging Error Messages 

When developing or debugging your VISA application, you may want to view 
internal VISA messages while your application is running. You can do this 
by using the Message Viewer utility (for Windows 95/98/Me), the Event 
Viewer utility (for Windows 2000/NT), or the Debug Window (for Windows 
95/98/2000/Me/NT). There are three choices for VISA logging: 

■ Off (default) for best performance 

■ Event Viewer/Message Viewer 

■ Debug Window 

Using the Event Viewer 

For Windows 2000 or Windows NT, the Event Viewer utility provides a 
way to view internal VISA error messages during application execution. 
Some of these internal messages do not represent programming errors and 
are actually error messages from VISA which are being handled internally 
by VISA. The process to use the Event Viewer is: 

■ Enable VISA logging from the Agilent 10 Libraries Control, click 

VISA Logging | Event Viewer. 

■ Run your VISA program. 

■ View VISA error messages by running the Event Viewer. 

From the Agilent 10 Libraries Control, click Run Event Viewer. 
VISA error messages will appear in the application log of the Event 
Viewer utility. 

Using the Message Viewer 

For Windows 95, Windows 98, or Windows Me, the Message Viewer utility 
provides a way to view internal VISA error messages during application 
execution. Some of these internal messages do not represent programming 
errors and are actually error messages from VISA which are being handled 
internally by VISA. 

The Message Viewer utility must be run BEFORE you run your VISA 
application. However, the utility will receive messages while minimized. 

This utility also provides menu selections for saving the logged messages to 
a file and for clearing the message buffer. 
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The process to use the Message Viewer is: 

■ Enable VISA logging from the Agilent 10 Libraries Control, click 
VISA Logging | Message Viewer. 

■ Start the Message Viewer. From the Agilent 10 Libraries Control, 
click Run Message Viewer. 

■ Run your VISA program. 

■ View error messages in the Message Viewer window. 

Using the Debug Window 

■ When VISA logging is directed to the Debug Window, VISA writes 
logging messages using the Win32 API call OutputDebugString(). 
The most common use for this feature is when debugging your VISA 
program using an application such as Microsoft Visual Studio. In this 
case, VISA messages will appear in the Visual Studio output 
window. The process to use the Debug Window is: 

■ Enable VISA logging from the Agilent 10 Libraries Control. Click 
VISA Logging | Debug Window. 

■ Run your VISA program from Microsoft Visual Studio (or 
equivalent application). 

■ View error messages in the Visual Studio (or equivalent) output 
window. 
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This chapter gives guidelines to build a VISA application on HP-UX version 
10.20 or later. The chapter contains the following sections: 

■ Building a VISA Program in HP-UX 

■ Using Online Help 
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Building a VISA Program in HP-UX 

This section lists and example program called idn that queries a GPIB 
instrument for its identification string. The idn example program is located 
in the following subdirectory: 

opt/vxipnp/hpux/hpvisa/share/examples 

Example Source Code 

The source file idn. c follows. An explanation of the various function calls in 
the example is provided directly after the program listing. 

/*idn. c 

This program queries a GPIB device for an ID string and prints 
the results. Note that you must change the address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
char buf [256] = {0}; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "GPIBO: :24: :INSTR" , VI_NULL,VI_NULL, &vi); 

/* Initialize device */ 
viPrintf(vi, "*RST\n"); 

/* Send an *IDN? string to the device */ 
viPrintf(vi, "*IDN?\n"); 

/* Read results */ 

viScanf(vi, "%t", buf) ; 

/* Print results */ 

printf ("Instrument identification string: %s\n", buf) ; 

/* Close sessions */ 
viClose(vi); 
viClose(defaultRM); 
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Example Program Contents 

A summary of the VISA function calls used in the example program follows. 
For a more detailed explanation of VISA functionality, see Chapter 4 - 
Programming with VISA. See Chapter 7 - VISA Language Reference for 
more detailed information on these VISA calls. 

visa.h. This file is included at the beginning of the file to provide the function 
prototypes and constants defined by VISA. 

ViSession. The ViSession is a VISA data type. Each object that will 
establish a communication channel must be defined as ViSession. 

viOpenDefaultRM. You must first open a session with the default resource 
manager with the viOpenDefaultRM function. This function will initialize 
the default resource manager and return a pointer to that resource manager 
session. 

viOpen. This function establishes a communication channel with the device 
specified. A session identifier that can be used with other VISA functions is 
returned. This call must be made for each device you will be using. 

viPrintf and viScanf. These are the VISA formatted I/O functions that are 
patterned after those used in the C programming language. The viPrintf 
call sends the IEEE 488.2 *rst command to the instrument and puts it in 
a known state. The viPrintf call is used again to query for the device 
identification (*idn?). The viScanf call is then used to read the results. 

viClose. This function must be used to close each session. When you close 
a device session, all data structures that had been allocated for the session 
will be deallocated. When you close the default manager session, all 
sessions opened using that default manager session will be closed. 

Running the Example Program 

To run the idn example program, type the program name at the command 
prompt. For example: 

idn 

If the program run correctly, the following is an example of the output if 
connected to a 54601A oscilloscope: 

Hewlett-Packard,54601A,0,1.7 
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If you have problems running the idn example program, first check to make 
sure the device address specified in your program is correct. If the program 
still does not run, check the I/O configuration. See the Agilent I/O Libraries 
Installation and Configuration Guide for HP-UX tot information on I/O 
configuration. 

Compiling and Linking a VISA Program 

You can create your VISA applications in ANSI C or C++. When compiling 
and linking a C program that uses VISA, use the -lvisa command line 
option to link in the VISA library routines. The following example creates the 
idn executable file: 

cc -Aa -o idn idn.c -lvisa 

■ The -Aa option indicates ANSI C 

■ The -o option creates an executable file called idn 

■ The -1 option links in the VISA library 

Logging Error Messages 

To view any VISA internal errors that may occur on HP-UX, edit the 
/etc/opt/vxipnp/hpux/hpvisa/hpvisa. ini file. Change the 
ErrorLog= line in this file to the following: 

ErrorLog=true 

The error messages, if any, will be then be printed to stderr. 
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Using Online Help 

Online help for VISA on HP-UX is provided with Bristol Technology's 
HyperHelp Viewer, or in the form of HP-UX manual pages (man pages), as 
explained in the following subsections. 

Using the HyperHelp Viewer 

The Bristol Technology HyperHelp Viewer allows you to view the VISA 
functions online. To start the HyperHelp Viewer with the VISA help file, 
type: 

hyperhelp/opt/hyperhelp/visahelp.hip 

When you start the Viewer, you can also specify any of the following options 


-k keyword 

Opens the Viewer and searches for the specified 

keyword. 

-p partial keyword 

Opens the Viewer and searches for a specific 

partial keywoi'd. 

-s viewmode 

Opens the Viewer in the specified viewmode. 

If 1 is specified as the viewmode, the Viewer is 
shared by all applications. If 0 is specified, a 
separate Viewer is opened for each application 
(default). 

-display display 

Opens the Viewer on the specified display. 


Using HP-UX Manual Pages 

To use manual pages, type the HP-UX man command followed by the VISA 
function name: 

man function 

The following are examples of selecting online help on VISA functions: 

man viPrintf 
man viScanf 
man viPeek 
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This chapter describes how to program with VISA. The basics of VISA are 
described, including formatted I/O, events and handlers, attributes, and 
locking. Example programs are also provided and can be found in the 
SAMPLES subdirectory on Windows environments or in the examples 
subdirectory on HP-UX. 

See Appendix A - VISA Library Information for the specific location of the 
example programs on your operating system. For specific details on VISA 
functions, see Chapter 7 - VISA Language Reference. This chapter contains 
the following sections: 

■ VISA Resources and Attributes 

■ Using Sessions 

■ Sending I/O Commands 

■ Using Events and Handlers 

■ Trapping Errors 

■ Using Locks 
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VISA Resources and Attributes 

This section introduces VISA resources and attributes, including: 

■ VISA Resources 

■ VISA Attributes 

VISA Resources 

In VISA, a resource is defined as any device (such as a voltmeter) with 
which VISA can provide communication. VISA defines six resource classes 
that a complete VISA system, fully compliant with the VXIplug&play Systems 
Alliance specification, can implement. Each resource class includes: 

■ Attributes to determine the state of a resource or session or to set 
a resource or session to a specified state. 

■ Events for communication with applications. 

■ Operations (functions) that can be used for the resource class. 

A summary description of each resource class supported by Agilent VISA 
follows. See Appendix B - VISA Resource Classes for a description of the 
attributes, events, and operations for each resource class. 


NOTE 

Although the Servant Device-Side (SERVANT) resource is defined by the 
VISA specification, the SERVANT resource is not supported by Agilent 
VISA. See Appendix B - VISA Resource Classes for a description of the 
SERVANT resource. 


Resource Class 

Interface Types 

Resource Class Description 

Instrument Control (INSTR) 

Generic, GPIB, GPIB-VXI, 
Serial, TCPIP, VXI 

Device operations (reading, writing, 
triggering, etc.). 

GPIB Bus Interface (INTFC) 

Generic, GPIB 

Raw GPIB interface operations (reading, 
writing, triggering, etc.). 

Memory Access (MEMACC) 

Generic, GPIB-VXI, VXI 

Address space of a memory-mapped bus 
such as the VXIbus. 
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Resource Class 

Interface Types 

Resource Class Description 

VXI Mainframe Backplane 
(BACKPLANE) 

Generic, GPIB-VXI, VXI 
(GPIB-VXI BACKPLANE 
not supported) 

VXI-defined operations and properties of 
each backplane (or chassis) in a VXIbus 
system. 

Servant Device-Side Resource 
(SERVANT) 

GPIB, VXI, TCPIP (not 
supported) 

Operations and properties of the 
capabilities of a device and a device's 
view of the system in which it exists. 

TCPIP Socket (SOCKET) 

Generic, TCPIP 

Operations and properties of a raw 
network socket connection using TCPIP. 


VISA Attributes 

Attributes are associated with resources or sessions. You can use attributes 
to determine the state of a resource or session or to set a resource or 
session to a specified state. 

For example, you can use the viGetAttribute function to read the state 
of an attribute for a specified session, event context, or find list. There are 
read only (RO) and read/write (RW) attributes. Use the viSetAttribute 
function to modify the state of a read/write attribute for a specified session, 
event context, or find list. 

The pointer passed to viGetAttribute must point to the exact type 
required for that attribute: ViUlntl6, vilnt32, etc. For example, when 
reading an attribute state that returns a ViUlntl6, you must declare a 
variable of that type and use it for the returned data. Ifvistring is 
returned, you must allocate an array and pass a pointer to that array for the 
returned data. 


Example: Reading a This example reads the state of the vi_attr_termchar_en attribute and 
VISA Attribute changes it if it is not true. 

ViBoolean state, newstate; 
newstate=VI TRUE; 

viGetAttribute(vi, VI_ATTR_TERMCHAR_EN, Sstate); 
if (state err !=VI_TRUE) viSetAttribute(vi, 

VI ATTR_TERMCHAR^EN, newstate); 
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Using Sessions 

This section shows how to use VISA sessions, including: 

■ Including the VISA Declarations File (C/C++) 

■ Adding the visa32.bas File (Visual Basic) 

■ Opening a Session to a Resource 

■ Addressing a Session 

■ Closing a Session 

■ Searching for Resources 

Including the VISA Declarations File (C/C++) 

For C and C++ programs, you must include the visa. h header file at the 
beginning of every file that contains VISA function calls: 

#include "visa.h" 

This header file contains the VISA function prototypes and the definitions for 
all VISA constants and error codes. The visa.h header file also includes the 
visatype.h header file. 

The visatype.h header file defines most of the VISA types. The VISA types 
are used throughout VISA to specify data types used in the functions. For 
example, the viOpenDefaultRM function requires a pointer to a parameter 
of type ViSession. If you find ViSession in the visatype.h header file, 
you will find that ViSession is eventually typed as an unsigned long. VISA 
types are also listed in Appendix A - VISA System Information. 

Adding the visa32.bas File (Visual Basic) 

You must add the visa32.bas Basic Module file to your Visual Basic Project. 
The visa32.bas file contains the VISA function prototypes and definitions for 
all VISA constants and error codes. 

Opening a Session 

A session is a channel of communication. Sessions must first be opened on 
the default resource manager, and then for each resource you will be using. 

■ A resource manager session is used to initialize the VISA system. 

It is a parent session that knows about all the opened sessions. A 
resource manager session must be opened before any other 
session can be opened. 
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■ A resource session is used to communicate with a resource on an 
interface. A session must be opened for each resource you will be 
using. When you use a session you can communicate without 
worrying about the type of interface to which it is connected. This 
insulation makes applications more robust and portable across 
interfaces. 

Resource Manager 
Sessions 

There are two parts to opening a communications session with a specific 
resource. First, you must open a session to the default resource manager 
with the viOpenDefaultRM function. The first call to this function initializes 
the default resource manager and returns a session to that resource 
manager session. You only need to open the default manager session once. 
However, subsequent calls to viOpenDefaultRM returns a unique session 
to the same default resource manager resource. 

Resource Sessions 

Next, you open a session with a specific resource with the viOpen function. 
This function uses the session returned from viOpenDefaultRM and 
returns its own session to identify the resource session. The following shows 
the function syntax: 

viOpenDefaultRM (sesn) ; 

viOpen (sesn, rsrcName, accessMode, timeout, w); 

The session returned from viOpenDefaultRM must be used in the sesn 
parameter of the viOpen function. The viOpen function then uses that 
session and the resource address specified in the rsrcName parameter to 
open a resource session. The vi parameter in viOpen returns a session 
identifier that can be used with other VISA functions. 

Your program may have several sessions open at the same time by creating 
multiple session identifiers by calling the viOpen function multiple times. 
The following table summarizes the parameters in the previous function 
calls. 

Parameter 

Description 

sesn 

A session returned from the viOpenDefaultRM function that identifies the 
resource manager session. 

rsrcName 

A unique symbolic name of the resource (resource address). 
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Parameter 

Description 

accessMode 

Specifies the modes by which the resource is to be accessed. The value 
vi exclusive lock is used to acquire an exclusive lock immediately upon 
opening a session. If a lock cannot be acquired, the session is closed and an 
error is returned. The vi load CONFIG value is used to configure attributes 
specified by some external configuration utility. If this value is not used, the 
session uses the default values provided by this specification. 

Multiple access modes can be used simultaneously by specifying a "bit-wise 
OR" of the values. (Must use vi null in VISA 1.0.). 

timeout 

If the accessMode parameter requires a lock, this parameter specifies the 
absolute time period (in milliseconds) that the resource waits to get unlocked 
before this operation returns an error. Otherwise, this parameter is ignored. 

(Must use vi null in VISA 1.0.) 

vi 

This is a pointer to the session identifier for this particular resource session. 

This pointer will be used to identify this resource session when using other 

VISA functions. 


Example: Opening a This example shows one way of opening resource sessions with a GPIB 
Resource Session multimeter and a GPIB-VXI scanner. The example first opens a session 

with the default resource manager. The session returned from the resource 
manager and a resource address is then used to open a session with the 
GPIB device at address 22. That session will now be identified as dmm 
when using other VISA functions. 

The session returned from the resource manager is then used again with 
another resource address to open a session with the GPIB-VXI device at 
primary address 9 and VXI logical address 24. That session will now be 
identified as scanner when using other VISA functions. See "Addressing 
a Session" for information on addressing particular devices. 

ViSession defaultRM, dmm, scanner; 

viOpenDefaultRM(&defaultRM); 

viOpen (defaultRM, "GPIBO : : 22 : : INSTR" , VI_NULL, 

VI_NULL, &dmm) ; 

viCpen(defaultRM, "GPIB-VXIO::24::INSTR", VI_NULL, 

VI_NULL,Sscanner); 

viClose(scanner); 

viClose(dmm); 

viClose(defaultRM); 
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Addressing a Session 

As shown in the previous section, the rsrcName parameter in the viOpen 
function is used to identify a specific resource. This parameter consists of 
the VISA interface name and the resource address. The interface name is 
determined when you run the VISA configuration utility. This name is usually 
the interface type followed by a number. 

The following table illustrates the format of the rsrcName for different 
interface types, instr is an optional parameter that indicates that you are 
communicating with a resource that is of type instr, meaning instrument. 
The keywords are: 

■ asrl establishes communication with asynchronous serial devices. 

■ gpib establishes communication with GPIB devices or interfaces. 

■ gpib-vxi is used for GPIB-VXI controllers. 

■ tcpip establishes communication with LAN instruments. 

■ vxi is used for VXI instruments. 


Interface 

Typical Syntax 

ASRL 

asrl [ board] [:: instr] 

GPIB 

gpib [ board] : : primary address [: : secondary address ] [: : instr] 

GPIB 

gpib [board] : :INTFC 

GPIB-VXI 

gpib-vxi [board] : : VXI logical address [: : INSTR] 

GPIB-VXI 

gpib-vxi [board] : :MEMACC 

GPIB-VXI 

gpib-vxi [board] [:: VXI logical address] : : backplane 

TCPIP 

tcpip [board] : -.host address]: -.LAN device name] : : instr 

TCPIP 

tcpip [board] : -.host address: -.port: : socket 

VXI 

vxi [board] : : VXI logical address [: : instr] 

VXI 

vxi [board] : :MEMACC 

VXI 

vxi [board] [:: VXI logical address] : : backplane 
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The following table describes the parameters used above. 


Parameter 

Description 

board 

This optional parameter is used if you have more 
than one interface of the same type. The default 
value for board is 0. 

host address 

The IP address (in dotted decimal notation) or the 
name of the host computer/gateway. 

LAN device name 

The assigned name for a LAN device. The default is 
inst(). 

port 

The port number to use for a TCP/IP Socket 
connection. 

primary address 

This is the primary address of the GPIB device. 

secondary address 

This optional parameter is the secondary address of 
the GPIB device. If no secondary address is 
specified, none is assumed. 

VXI logical address 

This is the logical address of the VXI instrument. 


Some examples of valid symbolic names follow. 


Address String 

Description 

VXI0::1::INSTR 

A VXI device at logical address 1 in VXI interface 
VXIO. 

GPIB- VXI::9::INS TR 

A VXI device at logical address 9 in a GPIB-VXI 
controlled VXI system. 

GPIB::1::0::INSTR 

A GPIB device at primary address 1 and secondary 
address 0 in GPIB interface 0. 

ASRL1 ::INSTR 

A serial device located on port 1. 

VXL.MEMACC 

Board-level register access to the VXI interface. 

GPIB-VXI1 ::MEMACC 

Board-level register access to GPIB-VXI interface 
number 1. 

GPIB2::INTFC 

Interface or raw resource for GPIB interface 2. 
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Example: Opening a 
Session 


VXI::1-BACKPLANE 

Mainframe resource for chassis 1 on the default VXI 
system, which is interface 0. 

GPIB-VXI2:: 

BACKPLANE 

Mainframe resource for default chassis on GPIB-VXI 
interface 2. 

GPIB1-SERVANT 

Servant/device-side resource for GPIB interface 1. 

VXIO-SERVANT 

Servant/device-side resource for VXI interface 0. 

TCPIPO-1.2.3.4-999- 
SOCKET 

Raw TCPIP access to port 999 at the specified 
address. 

T CPtP::devicename@ 
company. com::INSTR 

TCPIP device using VXI-11 located at the specified 
address. This uses the default LAN Device Name of 
instO. 


This example shows one way to open a resource session with the GPIB 
device at primary address 23. 

ViSession defaultRM, vi; 


viOpenDefaultRM(&defaultRM); 

viOpen (defaultRM, "GPIBO : : 23 : : INSTR" , VI_NULL, 
VI_NULL,&vi); 


viClose(vi); 
viClose(defaultRM); 

Closing a Session 

The viClose function must be used to close each session. You can close 
the specific resource session, which will free all data structures that had 
been allocated for the session. If you close the default resource manager 
session, all sessions opened using that resource manager session will be 
closed. 

Since system resources are also used when searching for resources 
(viFindRsrc), the viClose function needs to be called to free up find lists. 
See "Searching for Resources" for more information on closing find lists. 
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Searching for Resources 

When you open the default resource manager, you are opening a parent 
session that knows about all the other resources in the system. Since the 
resource manager session knows about all resources, it has the ability to 
search for specific resources and open sessions to these resources. You 
can, for example, search an interface for devices and open a session with 
one of the devices found. 

Use the viFindRsrc function to search an interface for device resources. 
This function finds matches and returns the number of matches found 
and a handle to the resources found. If there are more matches, use the 
viFindNext function with the handle returned from viFindRsrc to 
get the next match: 

viFindRsrc ( sesn, expr, findList, retcnt, instrDesc ); 


viFindNext (findList, instrDesc ); 


viClose (findList)] 

Where the parameters are defined as follows. 


Parameter 

Description 

sesn 

The resource manager session. 

expr 

The expression that identifies what to search (see table that 
follows). 

findList 

A handle that identifies this search. This handle will then be used 
as an input to the viFindNext function when finding the next 
match. 

retcnt 

A pointer to the number of matches found. 

instrDesc 

A pointer to a string identifying the location of the match. Note 
that you must allocate storage for this string. 


The handle returned from viFindRsrc should be closed to free up all the 
system resources associated with the search. To close the find object, pass 
the findList to the viClose function. 
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Resources 


Use the expr parameter of the viFindRsrc function to specify the interface 
to search. You can search for devices on the specified interface. Use the 
following table to determine what to use for your expr parameter. 

NOTE 

Because VISA interprets strings as regular expressions, the string 
GPIB?*INSTR applies to both GPIB and GPIB-VXI devices. 


Interface 

expr Parameter 

GPIB 

GPIB[0-9]*::?*INSTR 

VXI 

VXI?*INSTR 

GPIB-VXI 

GPIB-VXI?*INSTR 

GPIB and GPIB-VXI 

GPIB?*INSTR 

All VXI 

?*VXI[0-9]*::?*INSTR 

ASRL 

ASRL[0-9]*::?*INSTR 

All 

?*INSTR 


This example searches the VXI interface for resources. The number of 
matches found is returned in nmatches, and matches points to the string that 
contains the matches found. The first call returns the first match found, the 
second call returns the second match found, etc. vi_find_buflen is 
defined in the visa.h declarations file. 

ViChar buffer [VI_FIND_BUFLEN]; 

ViRsrc matches=buffer; 

ViUInt32 nmatches; 

ViFindList list; 


viFindRsrc(defaultRM, "VXI?*INSTR", Slist, &nmatches, 
matches); 

viFindNext(list, matches); 

viClose(list); 
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Sending I/O Commands 

This section gives guidelines to send I/O commands, including: 

■ Types of I/O 

■ Using Formatted I/O 

■ Using Non-Formatted I/O 

Types of I/O 

Once you have established a communications session with a device, you 
can start communicating with that device using VISA'S I/O routines. VISA 
provides both formatted and non-formatted I/O routines. 

■ Formatted I/O converts mixed types of data under the control of a 
format string. The data is buffered, thus optimizing interface traffic. 

■ Non-formatted I/O sends or receives raw data to or from a device. 
With non-formatted I/O, no format or conversion of the data is 
performed. Thus, if formatted data is required, it must be done by 
the user. 

You can choose between VISA'S formatted and non-formatted I/O routines. 
However, since the non-formatted I/O performs the low-level I/O, you should 
not mix formatted I/O and non-formatted I/O in the same session. See the 
following sections for descriptions and examples using formatted I/O and 
non-formatted I/O in VISA. 

Using Formatted I/O 

The VISA formatted I/O mechanism is similar to the C stdio mechanism. 
The VISA formatted I/O functions are viPrintf, viQueryf , and 
viScanf . There are also two non-buffered and non-formatted I/O functions 
that synchronously transfer data, called viRead and viWrite and two that 
asynchronously transfer data, called viReadAsync and viWriteAsync. 

These are raw I/O functions and do not intermix with the formatted I/O 
functions. See "Using Non-Formatted I/O" in this chapter. See Chapter 7 - 
VISA Language Reference for more information on how data is converted 
under the control of the format string. 
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As noted, the VISA formatted I/O functions are viPrintf, viQueryf , and 
viScanf. 

■ The viPrintf functions format according to the format string and 
send data to a device. The viPrintf function sends separate arg 
parameters, while the viVPrintf function sends a list of 
parameters in params : 

viPrintf (vi, writeFmt[, arg1][, arg2][, 
viVPrintf (vi, writeFmt, params)-, 

■ The viScanf functions receive and convert data according to the 
format string. The viScanf function receives separate arg 
parameters, while the vivscanf function receives a list of 
parameters in params : 

viScanf (vi, readFmt[, arg1][, arg2][, ...])-, 
vivscanf ( vi, readFmt, params)-, 

■ The viQueryf functions format and send data to a device and then 
immediately receive and convert the response data. Hence, the 
viQueryf function is a combination of the viPrintf and 
viScanf functions. Similarly, the viVQueryf function is a 
combination of the viVPrintf and viVScanf functions. The 
viQueryf function sends and receives separate arg parameters, 
while the viVQueryf function sends and receives a list of 
parameters in params'. 

viQueryf (vi, writeFmt, readFmt[, arg1][, arg2][, .../); 
viVQueryf (vi, writeFmt, readFmt, params)-, 

The formatted I/O functions convert data under the control of the format 
string. The format string specifies how the argument is converted before it is 
input or output. The format specifier sequence consists of a % (percent) 
followed by an optional modifier(s), followed by a format code. 

% {modifiers\format code 

Zero or more modifiers may be used to change the meaning of the format 
code. Modifiers are only used when sending or receiving formatted I/O. To 
send formatted I/O, the asterisk (*) can be used to indicate that the number 
is taken from the next argument. 
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Example: Using 
Field Width Modifier 


However, when the asterisk is used when receiving formatted I/O, it 
indicates that the assignment is suppressed and the parameter is discarded. 
Use the pound sign (#) when receiving formatted I/O to indicate that an 
extra argument is used. The following are supported modifiers. See the 
viPrintf function in Chapter 1 - VISA Language Reference for additional 
enhanced modifiers (@1, @2, @3, @H, @Q, or @b). 

■ Field Width. Field width is an optional integer that specifies how 
many characters are in the field. If the viPrintf or viQueryf 
( writeFmt ) formatted data has fewer characters than specified in the 
field width, it will be padded on the left, or on the right if the - flag is 
present. 

You can use an asterisk (*) in place of the integer in viPrintf or 
viQueryf ( writeFmt ) to indicate that the integer is taken from the 
next argument. For the viScanf or viQueryf ( readFmt ) functions, 
you can use a # sign to indicate that the next argument is a 
reference to the field width. 

The field width modifier is only supported with viPrintf and 
viQueryf ( writeFmt ) format codes d, f, s, and viScanf and 
viQueryf {readFmt) format codes c, s, and []. 


The following example pads numb to six characters and sends it to 
the session specified by vr. 

int numb = 61 ; 
viPrintf ( vi, "%6d\n", numb); 

Inserts four spaces, for a total of 6 characters: 61 

■ .Precision. Precision is an optional integer preceded by a period. 
This modifier is only used with the viPrintf and viQueryf 
( writeFmt ) functions. The meaning of this argument is dependent on 
the conversion character used. You can use an asterisk (*) in place 
of the integer to indicate the integer is taken from the next argument. 
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Example: Using the 
Precision Modifier 


Format Code 

Description 

d 

Indicates the minimum number of digits to appear is 
specified for the @1, @H, @Q, and @B flags, and the 
i, o, u, x, and X format codes. 

f 

Indicates the maximum number of digits after the 
decimal point is specified. 

s 

Indicates the maximum number of characters for the 
string is specified. 

g 

Indicates the maximum significant digits are specified. 


This example converts numb so that there are only two digits to the 
right of the decimal point and sends it to the session specified by vi: 

float numb = 26.9345; 
viPrintf (vi, "%.2f\n", numb) ; 

Sends:26.93 

■ Argument Length Modifier. The meaning of the optional argument 
length modifier h, 1, L, z'' or z is dependent on the conversion 
character, as listed in the following table. Note that z and z are not 
ANSI C standard modifiers. 


Argument 

Length 

Modifier 

Format 

Codes 

Description 

h 

d, b, B 

Corresponding argument is a short integer or 
a reference to a short integer for d. For b or 

B, the argument is the location of a block of 
data or a reference to a data array. (B is only 
used with viPrintf or viQueryf (writeFmt).) 

1 

d,f, 
b, B 

Corresponding argument is a long integer or 
a reference to a long integer for d. Forf, the 
argument is a double float or a reference to a 
double float. For b or B, the argument is the 
location of a block of data or a reference to a 
data array. (B is only used with viPrintf or 
viQueryf (writeFmt).) 
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Argument 

Length 

Modifier 

Format 

Codes 

Description 

L 

f 

Corresponding argument is a long double or 
a reference to a long double. 

z 

b, B 

Corresponding argument is an array of floats 
or a reference to an array of floats. (B is only 
used with viPrintf or viQueryf (writeFmt).) 

z 

b, B 

Corresponding argument is an array of 
double floats or a reference to an array of 
double floats. (B is only used with viPrintf or 
viQueryf (writeFmt).) 


■ , Array Size. The comma operator is a format modifier that allows 
you to read or write a comma-separated list of numbers (only valid 
with %d and %f format codes). It is a comma followed by an integer. 
The integer indicates the number of elements in the array. The 
comma operator has the format of , dd where dd is the number of 
elements to read or write. 

For viPrintf or viQueryf ( writeFmt ), you can use an asterisk 
(*) in place of the integer to indicate that the integer is taken from 
the next argument. For viScanf or viQueryf ( readFmt ), you can 
use a # sign to indicate that the next argument is a reference to the 
array size. 


Example: Using 
Array Size Modifier 


■ Special Characters. Special formatting character sequences will 
send special characters. The following describes the special 
characters and what will be sent. 

The format string for viPrintf and viQueryf ( writeFmt ) puts a 
special meaning on the newline character (\n). The newline 
character in the format string flushes the output buffer to the device. 


This example specifies a comma-separated list to be sent to the 
session specified by vi: 

int list[5]={101,102,103,104,105}; 
viPrintf (vi, "%,5d\n", list); 

Sends: 101,102,103,104,105 
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All characters in the output buffer will be written to the device with an 
END indicator included with the last byte (the newline character). 
This means you can control at what point you want the data written 
to the device. If no newline character is included in the format string, 
the characters converted are stored in the output buffer. It will 
require another call to viPrintf, viQueryf ( writeFmt ), or 
viFlush to have those characters written to the device. 

This can be very useful in queuing up data to send to a device. It 
can also raise I/O performance by doing a few large writes instead 
of several smaller writes. The * while using the viScanf functions 
acts as an assignment suppression character. The input is not 
assigned to any parameters and is discarded. 

The grouping operator () in a regular expression has the highest 
precedence, the + and * operators in a regular expression have the 
next highest precedence after the grouping operator, and the or 
operator | in a regular expression has the lowest precedence. 
Some example expressions follow the table. 


Special 

Characters and 
Operators 

Description 

? 

Matches any one character. 

\ 

Makes the character that follows it an ordinary character 
instead of special character. For example, when a question 
mark follows a backslash (e.g.,’ '\?'), it matches the '?' 
character instead of any one character. 

[list] 

Matches any one character from the enclosed list. A hyphen 
can be used to match a range of characters. 

[''list] 

Matches any character not in the enclosed list. A hyphen 
can be used to match a range of characters. 

★ 

Matches 0 or more occurrences of the preceding character 
or expression. 

+ 

Matches 1 or more occurrences of the preceding character or 
expression. 

exp |exp 

Matches either the preceding or following expression. The or 
operator | matches the entire expression that precedes or 
follows it and not just the character that precedes or follows it. 
For example, vxi |GPIB means (vxi) | (GPIB) , not 

VXI(I|G)PIB. 


54 


Chapter 4 












Programming with VISA 

Sending I/O Commands 


Special 

Characters and 
Operators 

Description 

(exp) 

Grouping characters or expressions. 

\\ \\ 

Sends a blank space. 

\n 

Sends the ASCII line feed character. The END identifier will 
also be sent. 

\r 

Sends an ASCII carriage return character. 

\t 

Sends an ASCII TAB character. 

\### 

Sends ASCII character specified by octal value. 

\" 

Sends the ASCII double quote character. 

\\ 

Sends a backslash character. 


Example Expression 

Sample Matches 

GPIB?*INSTR 

Matches GPIBO : : 2: : INSTR, 

GPIBl: :1: :1: :INSTR, and GPIB- 
VXI1::8::INSTR 

GPIB[0-9]*::?*INSTR 

Matches GPIBO : : 2: : INSTR and 

GPIBl : : 1: : 1: : INSTR but not 

GPIB-VXI1::8::INSTR 

GPIB[0-9]::?*INSTR 

Matches GPIBO : : 2: : INSTR and 

GPIBl : : 1: : 1: : INSTR but not 

GPIB12::8::INSTR. 

GPIB[ A 0]::?*INSTR 

Matches GPIBl: : 1: : 1: : INSTR but not 

GPIBO::2::INSTR or GPIB12::8::INSTR 

VXI?*INSTR 

Matches VXIO : : 1: : INSTR but not 

GPIB-VXIO::1::INSTR 

GPIB-VXI?*INSTR 

Matches GPIB-VXIO: : 1: : INSTR but not 

VXIO::1::INSTR 

?*VXI[0-9]*::?*INSTR 

Matches VXIO: :1: : INSTR and 

GPIB-VXIO::1::INSTR 

ASRL[0-9]*::?*INSTR 

Matches ASRL1: : INSTR but not 

VXIO::5::INSTR 

ASRL1+::INSTR 

Matches ASRL1: : INSTR and ASRLll: : INSTR 
but not ASRL2: :INSTR 
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Example Expression 

Sample Matches 

(GPIB|VXI)?*INSTR 

Matches GPIB1: : 5: : INSTR and 

VXIO : : 3 : : INSTR but not ASRL2 : : INSTR 

(GPIBO|VXIO)::1::INSTR 

Matches GPIBO : : 1: : INSTR and 

VXIO::1::INSTR 

?*INSTR 

Matches all instr (device) resources 

?*VXI[0-9]*::?*MEMACC 

Matches vxio: :MEMACC and 

GPIB-VXIl::MEMACC 

VXIO::?* 

Matches VXIO : : 1: : INSTR, VXIO : : 2: : INSTR, 
and VXIO::MEMACC 

?* 

Matches all resources 


Format Codes. This table summarizes the format codes for sending and 
receiving formatted I/O. 


Format Codes 

Description 

viPrintf/viVPrintf and viQueryf/viVqueryf ( writeFmt) 

d, i 

Corresponding argument is an integer. 

f 

Corresponding argument is a double. 

c 

Corresponding argument is a character. 

s 

Corresponding argument is a pointer to a null terminated string. 

% 

Sends an ASCII percent (%) character. 

o, u, x, X 

Corresponding argument is an unsigned integer. 

e, E, g, G 

Corresponding argument is a double. 

n 

Corresponding argument is a pointer to an integer. 

b, B 

Corresponding argument is the location of a block of data. 

viPrintf/viVPrintf and viQueryf/viVqueryf ( readFmt) 

d,i,n 

Corresponding argument must be a pointer to an integer. 

e,f,g 

Corresponding argument must be a pointer to a float. 

c 

Corresponding argument is a pointer to a character sequence. 

s,t,T 

Corresponding argument is a pointer to a string. 

o,u,x 

Corresponding argument must be a pointer to an unsigned 
integer. 
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Format Codes 

Description 

[ 

Corresponding argument must be a character pointer. 

b 

Corresponding argument is a pointer to a data array. 


Example: Receiving 
Data From a 
Session 


This example receives data from the session specified by the vi parameter 
and converts the data to a string. 

char data[180]; 
viScanf (vi, "%t", data); 


Formatted I/O 
Buffers 


The write buffer is maintained by the viPrintf or viQueryf ( writeFmt) 
functions. The buffer queues characters to send to the device so that they 
are sent in large blocks, thus increasing performance. The write buffer 
automatically flushes when it sends a newline character from the format 
string. It may occasionally be flushed at other non-deterministic times, such 
as when the buffer fills. 

When the write buffer flushes, it sends its contents to the device. If you set 
the VI_ATTR_WR_BUF_OPER_MODE attribute to VI_FLUSH_ON_ACCESS, 
the write buffer will also be flushed every time a viPrintf or viQueryf 
operation completes. See "VISA Attributes" in this chapter for information 
on setting VISA attributes. 

The read buffer is maintained by the viScanf and viQueryf ( readFmt ) 
functions. It queues the data received from a device until it is needed by the 
format string. Flushing the read buffer destroys the data in the buffer and 
guarantees that the next call to viScanf or viQueryf reads data directly 
from the device rather than data that was previously queued. 

If you set the vi_attr_rd_buf_oper_mode attribute to 
vi_flush_on_access, the read buffer will be flushed every time a 
viScanf or viQueryf operation completes. See "VISA Attributes" in this 
chapter for information on setting VISA attributes. 


The VISA software maintains both a read and write buffer for formatted I/O 
operations. Occasionally, you may want to control the actions of these 
buffers. You can modify the size of the buffer using the viSetBuf function. 
See Chapter 1 - VISA Language Reference for more information on this 
function. 
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Example: Sending 
and Receiving 
Formatted I/O 


You can manually flush the read and write buffers using the viFlush 
function. Flushing the read buffer also includes reading all pending response 
data from a device. If the device is still sending data, the flush process will 
continue to read data from the device until it receives an end indicator from 
the device. 


This C program example shows sending and receiving formatted I/O. The 
example opens a session with a GPIB device and sends a comma operator 
to send a comma-separated list. This example program is intended to show 
specific VISA functionality and does not include error trapping. Error 
trapping, however, is good programming practice and is recommended in 
your VISA applications. See "Trapping Errors" in this chapter. 

This example program is installed on your system in the SAMPLES 
subdirectory on Windows environments or in the examples subdirectory 
on HP-UX. See Appendix A - VISA Library Information for locations of 
example programs on your operating system. 

/*formatio.c 

This example program makes a multimeter measurement 
with a comma-separated list passed with formatted 
I/O and prints the results. You may need to change 
the device address. */ 

#include <visa.h> 

#include <stdio.h> 


void main () { 

ViSession defaultRM, vi; 
double res; 

double list [2] = {1,0.001}; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM(&efaultRM); 

viOpen (defaultRM, "GPIBO : : 22 : : INSTR" , VI_NULL, VI_NULL, 
&vi) ; 

/* Initialize device */ 
viPrintf(vi, "*RST\n"); 

/* Set up device and send comma separated list */ 
viPrintf(vi, "CALC:DBM:REF 50\n"); 
viPrintf(vi, "MEAS:VOLT:AC? %,2f\n", list); 
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/* Read results */ 
viScanf(vi, "%lf", Sres); 

/* Print results */ 

printf("Measurement Results: %lf\n", res); 

/* Close session */ 
viClose(vi); 
viClose(defaultRM);} 

Using Non-Formatted I/O 

There are two non-buffered, non-formatted I/O functions that synchronously 
transfer data called viRead and viwrite. Also, there are two non- 
formatted I/O functions that asynchronously transfer data called 
viReadAsync and viWriteAsync. These are raw I/O functions and 
do not intermix with the formatted I/O functions. 


The non-formatted I/O functions follow. For more information, see the 
viRead, viWrite, viReadAsync, viWriteAsync, and viTerminate 
functions in Chapter 7 - VISA Language Reference. 

■ viRead. The viRead function synchronously reads raw data from 
the session specified by the vi parameter and stores the results in 
the location where buf\s pointing. Only one synchronous read 
operation can occur at any one time. 

viRead (w, buf, count, retCount) ; 

■ viWrite. The viwrite function synchronously sends the data 
pointed to by buf to the device specified by vi. Only one 
synchronous write operation can occur at any one time. 

viwrite ( vi, buf, count, retCount) ; 

■ viReadAsync. The viReadAsync function asynchronously reads 
raw data from the session specified by the vi parameter and stores 
the results in the location where buf is pointing. This operation 
normally returns before the transfer terminates. Thus, the operation 
returns jobld, which you can use with either viTerminate to abort 
the operation or with an I/O completion event to identify which 
asynchronous read operation completed. 

viReadAsync (vi, buf, count, jobld) ; 
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■ viWriteAsync. The viWriteAsync function asynchronously 
sends the data pointed to by buf to the device specified by vi. 

This operation normally returns before the transfer terminates. 

Thus, the operation returns jobld, which you can use with either 
viTerminate to abort the operation or with anl/O completion event 
to identify which asynchronous write operation completed. 

viWriteAsync ( vi, buf, count, jobld) ; 

This example program illustrates using non-formatted I/O functions to 
communicate with a GPIB device. This example program is intended to 
show specific VISA functionality and does not include error trapping. Error 
trapping, however, is good programming practice and is recommended in 
your VISA applications. See "Trapping Errors" in this chapter. 

/*nonfmtio.c 

This example program measures the AC voltage on a 
multimeter and prints the results. You may need to 
change the device address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
char strres [20]; 
unsigned long actual; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM(&defaultRM); 

viOpen (defaultRM, "GPIBO : : 22 : : INSTR" , VI_NULL, VI_NULL, 
&vi) ; 

/* Initialize device */ 

viWrite(vi, (ViBuf)"*RST\n", 5, Sactual); 

/* Set up device and take measurement */ 
viWrite(vi, (ViBuf)"CALC:DBM:REF 50\n", 16, Sactual); 
viWrite(vi, (ViBuf)"MEAS:VOLT:AC? 1, 0.001\n", 23, 
Sactual); 

/* Read results */ 

viRead(vi, (ViBuf)strres, 20, Sactual); 
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/* NULL terminate the string */ 
strres[actual]=0; 

/* Print results */ 

printf("Measurement Results: %s\n", 

/* Close session */ 
viClose(vi); 
viClose(defaultRM) ; 


strres); 
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Using Events and Handlers 

This section gives guidelines to use events and handlers, including: 

■ Events and Attributes 

■ Using the Callback Method 

■ Using the Queuing Method 


Events and Attributes 

Events are special occurrences that require attention from your application. 
Event types include Service Requests (SRQs), interrupts, and hardware 
triggers. Events will not be delivered unless the appropriate events are 
enabled. 


NOTE 

VISA cannot callback to a Visual Basic function. Thus, you can only use 
the queuing mechanism in viEnableEvent. There is no way to install a 
VISA event handler in Visual Basic. 


There are two ways you can receive notification that an event has occurred: 

■ Install an event handler with vilnstallhandler, and enable one 
or several events with viEnableEvent. If the event was enabled 
with a handler, the specified event handler will be called when the 
specified event occurs. This is called a callback. 


NOTE 

VISA cannot callback to a Visual Basic function. This means that you can 
only use the VI_QUEUE mechanism in viEnableEvent. There is no way 
to install a VISA event handler in Visual Basic. 


■ Enable one or several events with viEnableEvent and call the 
viWaitOnEvent function. The viWaitOnEvent function will 
suspend the program execution until the specified event occurs or 
the specified timeout period is reached. This is called queuing. 
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The queuing and callback mechanisms are suitable for different 
programming styles. The queuing mechanism is generally useful for non- 
critical events that do not need immediate servicing. The callback 
mechanism is useful when immediate responses are needed. These 
mechanisms work independently of each other, so both can be enabled at 
the same time. By default, a session is not enabled to receive any events by 
either mechanism. 

The viEnableEvent operation can be used to enable a session to respond 
to a specified event type using either the queuing mechanism, the callback 
mechanism, or both. Similarly, the viDisableEvent operation can be 
used to disable one or both mechanisms. Because the two methods work 
independently of each other, one can be enabled or disabled regardless of 
the current state of the other. 


Events That can be The following table shows the events that are implemented for Agilent VISA 
Enabled for each resource class, where AP = Access Privilege, RO - Read Only, and 

RW = Read/Write. Note that some resource classes/events, such as the 
SERVANT class are not implemented by Agilent VISA and are not listed in 
the following tables. 

Once the application has received an event, information about that event 
can be obtained by using the viGetAttribute function on that particular 
event context. Use the VISA viReadSTB function to read the status byte of 
the service request.. 


Instrument Control (INSTR) Resource Events 


VI_EVENT_SERVICE_REQUEST 

Notification that a service request was received from the device. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

SERVICE REQ 
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VI_EVENT_VXI_SIGP 

Notification that a VXIbus signal or VXIbus interrupt was received from the device. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

VXI STOP 

VI ATTR SIGP 

STATUS ID 

The 16-bit Status/ID value 
retrieved during the IACK 
cycle or from the Signal 
register. 

RO 

ViUIntl6 

0 to FFFF h 


VI_EVENT_TRIG 

Notification that a trigger interrupt was received from the device. For VISA, the only triggers that can be 
sensed are VXI hardware triggers on the assertion edge (SYNC and ON trigger protocols only). 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1* 


* Agilent VISA can also return vi_trig_panel_in (exception to the VISA Specification) 


VI_EVENT_I0_C0MPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 
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VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

0 to FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 


ViString 

N/A 


Memory Access (MEMACC) Resource Event 


VI_EVENT_I0_C0MPLETION 

Notification that an asynchronous operation has completed 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

10 COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed. 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed. 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements that 
were asynchronously 
transferred. 

RO 

ViUInt32 

0 to FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 

RO 

ViString 

N/A 
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GPIB Bus Interface (INTFC) Resource Events 


VI_EVENT_GPIB_CIC 

Notification that the GPIB controller has gained or lost CIC (controller in charge) status 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

CIC 

VI ATTR GPIB RECV 

CIC STATE 

Controller has become 
controller-in-charge. 

RO 

ViBoolean 

VI TRUE 

VI FALSE 


VI_EVENT_GPIB_TALK 

Notification that the GPIB controller has been addressed to talk 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

TALK 


VI_EVENT_GPIB_LISTEN 

Notification that the GPIB controller has been addressed to listen. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

LISTEN 


VI_EVENT_CLEAR 

Notification that the GPIB controller has been sent a device clear message. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT CLEAR 
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VI_EVENT_TRIGGER 

Notification that a trigger interrupt was received from the interface. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG SW 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed. 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed. 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of buffer used in an 
asynchronous operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

0 to FFFFFFFF h 

VI ATTR OPER NAME 

The name of the operation 
generating the event. 

RO 

ViString 

N/A 
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VXI Mainframe Backplane (BACKPLANE) Resource Events 


VI_EVENT_TRIG 

Notification that a trigger interrupt was received from the backplane. For VISA, the only triggers that can 
be sensed are VXI hardware triggers on the assertion edge (SYNC and ON trigger protocols only). 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 


VI_EVENT_VXI_VME_SYSFAIL 

Notification that the VXI/VME SYSFAIL* line has been asserted. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT VXI 

VME SYSFAIL 


VI_EVENT_VXI_VME_SYSRESET 

Notification that the VXI/VME SYSRESET* line has been reset 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT VXI 

VME SYSRESET 


TCPIP Socket (SOCKET) Resource Event 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed 

RO 

ViStatus 

N/A 
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TCPIP Socket (SOCKET) Resource Event 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

0 to FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 

RO 

ViString 

N/A 


Example: Reading Once you have decided which attribute to check, you can read the attribute 
Event Attributes using the viGetAttribute function. The following example shows one 
way you could check which trigger line fired when the vi_event_trig 
event was delivered. 

Note that the context parameter is either the event context passed to your 
event handler, or the outcontext specified when doing a wait on event. See 
"VISA Attributes" in this chapter for more information on reading attribute 
states. 

Vilntl6 state; 


viGetAttribute (context, VI_ATTR_RECV_TRIG_ID, Sstate); 

Using the Callback Method 

The callback method of event notification is used when an immediate 
response to an event is required. To use the callback method for receiving 
notification that an event has occurred, you must do the following. Then, 
when the enabled event occurs, the installed event handler is called. 

■ Install an event handler with the vilnstallHandler function 

■ Enable one or several events with the viEnableEvent function 
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Example: Using the 
Callback Method 


Installing Handlers 


This example shows one way you can use the callback method. 

ViStatus VI FUNCH my handler (ViSession vi, 
ViEventType 

eventType, ViEvent context, ViAddr usrHandle) { 

/* your event handling code here */ 

return VI_SUCCESS; 

} 

main () { 

ViSession vi; 

ViAddr addr=0; 


vilnstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, 
addr); 

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR, 
VI_NULL); 

/* your code here */ 

viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR); 
viUninstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, 
addr); 


VISA allows applications to install multiple handlers for for an event type on 
the same session. Multiple handlers can be installed through multiple 
invocations of the vilnstallHandler operation, where each invocation 
adds to the previous list of handlers. 

If more than one handler is installed for an event type, each of the handlers 
is invoked on every occurrence of the specified event(s). VISA specifies that 
the handlers are invoked in Last In First Out (LIFO) order. Use the following 
function when installing an event handler: 

vilnstallHandler (vi, eventType, handler, userHandle) ; 

Where the parameters are defined as follows: 
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Example: Installing 
an Event Handler 


Writing the Handler 


Parameter 

Description 

vi 

The session on which the handler will be installed. 

eventType 

The event type that will activate the handler. 

handler 

The name of the handler to be called. 

userHandle 

A user value that uniquely identifies the handler for the 
specified event type. 


The userHandle parameter allows you to assign a value to be used with the 
handler on the specified session. Thus, you can install the same handler for 
the same event type on several sessions with different userHandle values. 
The same handler is called for the specified event type. 

However, the value passed to userHandle is different. Therefore the 
handlers are uniquely identified by the combination of the handler and the 
userHandle. This may be useful when you need a different handling method 
depending on the userHandle. 


This example shows how to install an event handler to call my_handler\Nhen 
a Service Request occurs. Note that vi_event_service_req must also 
be an enabled event with the viEnableEvent function for the service 
request event to be delivered. 

vilnstallHandler( vi, VI_EVENT_SERVICE_REQ, my_handler, 
addr) ; 

Use the viUninstallHandler function to uninstall a specific handler. 

Or you can use wildcards (vi_any_hndlr in the handler parameter) to 
uninstall groups of handlers. See viUninstallHandler in Chapter 7 - 
VISA Language Reference for more details on this function. 


The handler installed needs to be written by the programmer. The event 
handler typically reads an associated attribute and performs some sort of 
action. See the event handler in the example program later in this section. 
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Enabling Events 


Example: Enabling a 
Hardware Trigger 
Event 


Before an event can be delivered, it must be enabled using the 
viEnableEvent function. This function causes the application to be 
notified when the enabled event has occurred, Where the parameters are: 

viEnableEvent (vi, eventType, mechanism, context) ; 

Using vi_queue in the mechanism parameter specifies a queuing method 
for the events to be handled. If you use both vi_queue and one of the 
mechanisms listed above, notification of events will be sent to both 
locations. See the next subsection for information on the queuing method. 


Parameter 

Description 

vi 

The session on which the handler will be installed. 

eventType 

The type of event to enable. 

mechanism 

The mechanism by which the event will be enabled. It can be 
enabled in several different ways. You can use VI_HNDLR in 
this parameter to specify that the installed handler will be called 
when the event occurs. Use VI SUSPEND HNDLR in this 
parameter which puts the events in a queue and waits to call 
the installed handlers until viEnableEvent is called with 

VI HNDLR specified in the mechanism parameter. When 
viEnableEvent is called with VI HNDLR specified, the 
handler for each queued event will be called. 

context 

Not used in VISA 1.0. Use vi null. 


This example illustrates enabling a hardware trigger event. 

vilnstallHandler(vi, VI^EVENT TRIG, my handler , &addr); 
viEnableEvent(vi, VI_EVENT_TRIG, VI_HNDLR, VI_NULL); 

The vi_hndlr mechanism specifies that the handler installed for 
vi_event_trig will be called when a hardware trigger occurs. 

If you specify vi_all_enable_events in the eventType parameter, all 
events that have previously been enabled on the specified session will be 
enabled for the mechanism specified in this function call. 

Use the viDisableEvent function to stop servicing the event specified. 
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Example: Trigger 
Callback 


This example program installs an event handler and enables the trigger 
event. When the event occurs, the installed event handler is called. This 
program is intended to show specific VISA functionality and does not include 
error trapping. Error trapping, however, is good programming practice and is 
recommended in your VISA applications. See "Trapping Errors" in this 
chapter. 

This example program is installed on your system in the SAMPLES 
subdirectory on Windows environments or in the examples subdirectory 
on HP-UX. See Appendix A - VISA Library Information for locations of 
example programs on your operating system. 

/* evnthdlr.c 

This example program illustrates installing an event 
handler to be called when a trigger interrupt occurs. 
Note that you may need to change the address. */ 

#include <visa.h> 

#include <stdio.h> 

/* trigger event handler */ 

ViStatus VI FUNCH myHdlr(ViSession vi, ViEventType 
eventType, ViEvent ctx, ViAddr userHdlr){ 

Vilntl6 trigld; 

/* make sure it is a trigger event */ 
if(eventType!=VI_EVENT_TRIG){ 

/* Stray event, so ignore */ 
return VI_SUCCESS; 

} 

/* print the event information */ 

printf("Trigger Event Occurred!\n"); 

printf("...Original Device Session = %ld\n", vi); 

/* get the trigger that fired */ 

viGetAttribute(ctx, VI_ATTR_RECV_TRIG_ID, Strigld); 
printf("Trigger that fired: "); 
switch(trigld){ 

case VI_TRIG_TTLO: 
printf("TTLO") ; 
break; 
default: 

printf("<other Ox%x>", trigld); 
break; 

} 
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printf("\n"); 
return VI_SUCCESS; 

} 

void main(){ 

ViSession defaultRM,vi; 

/* open session to VXI device */ 
viOpenDefaultRM(&defaultRM); 

viOpen (defaultRM, "VXIO : : 24 : : INSTR" , VI_NULL, VI_NULL, 
&vi) ; 

/* select trigger line TTLO */ 

viSetAttribute(vi, VI_ATTR_TRIG_ID, VI_TRIG_TTLO); 

/* install the handler and enable it */ 
vilnstallHandler(vi, VI EVENT TRIG, myHdlr, 

(ViAddr)10) ; 

viEnableEvent(vi, VI_EVENT_TRIG, VI_HNDLR, VI_NULL); 
/* fire trigger line, twice */ 
viAssertTrigger(vi, VI_TRIG_PROT_SYNC); 
viAssertTrigger(vi, VI_TRIG_PROT_SYNC); 

/* unenable and uninstall the handler */ 
viDisableEvent(vi, VI_EVENT_TRIG, VI_HNDLR); 

viUninstallHandler(vi, VI EVENT TRIG, myHdlr, 

(ViAddr)10); 

/* close the sessions */ 
viClose(vi); 
viClose(defaultRM); 


Example: SRQ This program installs an event handler and enables an SRQ event. When 

Callback the event occurs, the installed event handler is called. This example 

program is intended to show specific VISA functionality and does not include 
error trapping. Error trapping, however, is good programming practice and is 
recommended in your VISA applications. See "Trapping Errors" in this 
chapter. 

This program is installed on your system in the SAMPLES subdirectory on 
Windows environments or in the examples subdirectory on HP-UX. See 
Appendix A - VISA Library Information for locations of example programs on 
your operating system. 
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/* srqhdlr.c 

This example program illustrates installing an event 
handler to be called when an SRQ interrupt occurs. 
Note that you may need to change the address. */ 

#include <visa.h> 

#include <stdio.h> 

#if defined ( WIN32) 

#include <windows.h> /* for SleepO */ 

#define YIELD Sleep( 10 ) 

#elif defined ( BORLANDC_) 

#include <windows.h> /* for YieldO */ 

#define YIELD YieldO 
#elif defined ( WINDOWS) 

#include <io.h> /* for wyield */ 

#define YIELD wyield() 

#else 

#include <unistd.h> 

#define YIELD sleep (1) 

#endif 

int srqOccurred; 

/* trigger event handler */ 

ViStatus VI_FUNCH mySrqHdlr(ViSession vi, ViEventType 
eventType, ViEvent ctx, ViAddr userHdlr){ 

ViUIntl6 statusByte; 

/* make sure it is an SRQ event */ 
if(eventType!=VI_EVENT_SERVICE_REQ){ 

/* Stray event, so ignore */ 

printf( "\nStray event of type 0x%lx\n", eventType 

) ; 

return VI_SUCCESS; 

} 

/* print the event information */ 

printf("\nSRQ Event Occurred!\n"); 

printf("...Original Device Session = %ld\n", vi); 

/* get the status byte */ 
viReadSTB(vi, SstatusByte); 

printf("...Status byte is 0x%x\n", statusByte); 

srqOccurred = 1; 
return VI SUCCESS; 
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void main(){ 

ViSession defaultRM,vi; 
long count; 

/* open session to message based VXI device */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "GPIB-VXIO::24::INSTR", VI_NULL, VI_NULL, 
&vi) ; 

/* Enable command error events */ 
viPrintf( vi, "*ESE 32\n" ); 

/* Enable event register interrupts */ 
viPrintf( vi, "*SRE 32\n" ); 

/* install the handler and enable it */ 
vilnstallHandler(vi, VI_EVENT_SERVICE_REQ, mySrqHdlr, 

(ViAddr)10); 

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI^HNDLR, 
VI_NULL); 

srqOccurred = 0; 

/* Send a bogus command to the message based device to 
cause an SRQ. Note: 'IDN' causes the error — 'IDN?' 
is the correct syntax */ 
viPrintf( vi, "IDN\n" ); 

/* Wait a while for the SRQ to be generated and for the 
handler to be called. Print something while we wait */ 

printf( "Waiting for an SRQ to be generated ." ); 
for (count = 0 ; (count < 10) && (srqOccurred == 

0);count++) { 

long count2 = 0; 
printf( "." ); 

while ( (count2++ < 100) && (srqOccurred ==0) ){ 

YIELD; 

} 

} 

printf( "\n" ); 

/* disable and uninstall the handler */ 
viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI^HNDLR); 
viUninstallHandler(vi, VI_EVENT_SERVICE_REQ, mySrqHdlr, 
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Example: Using the 
Queuing Method 


(ViAddr)10); 

/* Clean up - do not leave device in error state */ 
viPrintf( vi, "*CLS\n" ); 

/* close the sessions */ 

viClose(vi); 

viClose(defaultRM); 

printf( "End of program\n" );} 

Using the Queuing Method 

The queuing method is generally used when an immediate response from 
your application is not needed. To use the queuing method for receiving 
notification that an event has occurred, you must do the following: 

■ Enable one or several events with the viEnableEvent function. 

■ When ready to query, use the viWaitOnEvent function to check 
for queued events. 

If the specified event has occurred, the event information is retrieved and the 
program returns immediately. If the specified event has not occurred, the 
program suspends execution until a specified event occurs or until the 
specified timeout period is reached. 


This example program shows one way you can use the queuing method. 

main (); 

ViSession vi; 

ViEventType eventType; 

ViEvent event; 


viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE, 
VI NULL); 


viWaitOnEvent(vi, VI_EVENT_SERVICE_REQ, 
VI_TMO_INFINITE, 

SeventType, Sevent); 

viClose(event); 

viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE); 

} 
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Enabling Events 


Example: Enabling a 
Hardware Trigger 
Event 


Wait on the Event 


Before an event can be delivered, it must be enabled using the 
viEnableEvent function: 

viEnableEvent (vi, eventType, mechanism, context) ; 
where the parameters are defined as follows: 


Parameter 

Description 

vi 

The session the handler will be installed on. 

eventType 

The type of event to enable. 

mechanism 

The mechanism by which the event will be enabled. 
Specify vi queue to use the queuing method. 

context 

Not used in VISA 1.0. Use vi null. 


When you use vi_queue in the mechanism parameter, you are specifying 
that the events will be put into a queue. Then, when a viWaitOnEvent 
function is invoked, the program execution will suspend until the enabled 
event occurs or the timeout period specified is reached. If the event has 
already occurred, the viWaitOnEvent function will return immediately. 


This example illustrates enabling a hardware trigger event. 

viEnableEvent(vi, VI_EVENT_TRIG, VI_QUEUE, VI_NULL); 

The vi_queue mechanism specifies that when an event occurs, it will go 
into a queue. If you specify vi_all_enable_events in the eventType 
parameter, all events that have previously been enabled on the specified 
session will be enabled for the mechanism specified in this function call. 
Use the viDisableEvent function to stop servicing the event specified. 


When using the viWaitOnEvent function, specify the session, the event 
type to wait for, and the timeout period to wait: 

viWaitOnEvent (vi, inEventType, timeout, outEventType, outContext ) ; 

The event must have previously been enabled with vi_queue specified as 
the mechanism parameter. 
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Example: Wait on 
Event for SRQ 


Example: Trigger 
Event Queuing 


This example shows how to install a wait on event for service requests. 

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI^QUEUE, 
VI_NULL); 

viWaitOnEvent(vi, VI_EVENT_SERVICE_REQ, 
VI_TMO_INFINITE, 

SeventType, Sevent); 


viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE); 

Every time a wait on event is invoked, an event context object is created. 
Specifying vi_tmo_infinite in the timeout parameter indicates that the 
program execution will suspend indefinitely until the event occurs. To clear 
the event queue for a specified event type, use the viDiscardEvents 
function. 


This program enables the trigger event in a queuing mode. When the 
viWaitOnEvent function is called, the program will suspend operation until 
the trigger line is fired or the timeout period is reached. Since the trigger 
lines were already fired and the events were put into a queue, the function 
will return and print the trigger line that fired. 

This program is intended to show specific VISA functionality and does not 
include error trapping. Error trapping, however, is good programming 
practice and is recommended in your VISA applications. See "Trapping 
Errors" in this chapter. 

This example program is installed on your system in the SAMPLES 
subdirectory on Windows environments or in the examples subdirectory 
on HP-UX. See Appendix A - VISA Library Information for locations of 
example programs on your operating system. 

/* evntqueu.c 

This example program illustrates enabling an event 
queue using viWaitOnEvent. Note that you must change 
the device address. */ 

#include <visa.h> 

#include <stdio.h> 

void main(){ 

ViSession defaultRM,vi; 

ViEventType eventType; 

ViEvent eventVi; 

ViStatus err; 
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Vi Inti 6 trigld; 

/* open session to VXI device */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "VXIO::24::INSTR", VI_NULL, VI_NULL, 
&vi) ; 

/* select trigger line TTLO */ 

viSetAttribute(vi, VI_ATTR_TRIG_ID, VIJTRIGJTTLO) ; 

/* enable the event */ 

viEnableEvent(vi, VI_EVENT_TRIG, VI_QUEUE, VI_NULL); 

/* fire trigger line, twice */ 
viAssertTrigger(vi, VI_TRIG_PROT_SYNC); 
viAssertTrigger(vi, VI_TRIG_PROT_SYNC); 

/* Wait for the event to occur */ 

err=viWaitOnEvent(vi, VI EVENT TRIG, 10000, &eventType, 
SeventVi); 

if(err==VI_ERROR_TMO){ 

printf("Timeout Occurred! Event not received.\n"); 
return; 

} 

/* print the event information */ 

printf("Trigger Event Occurred!\n"); 

printf("...Original Device Session = %ld\n", vi); 

/* get trigger that fired */ 

viGetAttribute(eventVi, VI_ATTR_RECV_TRIG_ID, 

Strigld); 

printf("Trigger that fired: "); 
switch(trigld){ 

case VI_TRIG_TTL0: 
printf("TTLO"); 
break; 
default: 

printf("<other 0x%x>" , trigld) ; 
break; 

} 

printf("\n") ; 

/* close the context before continuing */ 
viClose(eventVi); 
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/* get second event */ 

err=viWaitOnEvent(vi, VI EVENT TRIG, 10000, &eventType, 
SeventVi); 

if(err==VI_ERROR_TMO){ 

printf("Timeout Occurred! Event not received.\n"); 
return; 

} 

printf("Got second event\n"); 

/* close the context before continuing */ 
viClose(eventVi); 

/* disable event */ 

viDisableEvent(vi, VI_EVENT_TRIG, VI_QUEUE); 

/* close the sessions */ 
viClose(vi); 
viClose(defaultRM); 
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Example: Check for 

VI SUCCESS 


Example: Printing 
Error Code 


Trapping Errors 

This section gives guidelines to trap errors, including: 

■ Trapping Errors 

■ Exception Events 

Trapping Errors 

The example programs in this guide show specific VISA functionality and 
do not include error trapping. Error trapping, however, is good programming 
practice and is recommended in all your VISA application programs. To trap 
VISA errors you must check for vi_success after each VISA function call. 

If you want to ignore WARNINGS, you can test to see if err is less than (<) 
VI_SUCCESS. Since WARNINGS are greater than vi_success and 
ERRORS are less than VI_SUCCESS, err_handler would only be called 
when the function returns an ERROR. For example: 

if (err < VI_SUCCESS) err^handler ( VI, err); 

This example illustrates checking for vi_success. If vi_success is not 
returned, an error handler (written by the programmer) is called. This must 
be done with each VISA function call. 

ViStatus err; 


err=viPrintf(vi, "*RST\n"); 

if (err < VI SUCCESS) err handler(vi, err); 


The following error handler prints a user-readable string describing the error 
code passed to the function: 

void err handler(ViSession vi, ViStatus err){ 

char err msg[1024]={0} ; 
viStatusDesc (vi, err, err_msg); 
printf ("ERROR = %s\n", err msg) ; 
return; 

} 
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Example: Checking 
Instrument Errors 


Exception Handling 
Model 


When programming instruments, it is good practice to check the instrument 
to ensure there are no instrument errors after each instrument function. This 
example uses a SCPI command to check a specific instrument for errors. 

void system err(){ 

ViStatus err; 
char buf[1024]={0}; 
int err no; 

err=viPrintf(vi, "SYSTEM:ERR?\n"); 

if (err < VI^SUCCESS) err handler (vi, err); 

err=viScanf (vi, "%d%t", Serrano, &buf); 
if (err < VI^SUCCESS) err handler (vi, err); 

while (err^no >0){ 

printf ("Error Found: %d,%s\n", err no, buf); 
err=viScanf (vi, "%d%t", &err_no, &buf); 

} 

err=viFlush(vi, VI READ BUF); 

if (err < VI^SUCCESS) err handler (vi, err); 

err=viFlush(vi, VI_WRITE_BUF) ; 

if (err < VI^SUCCESS) err handler (vi, err); 

} 

Exception Events 

An alternative to trapping VISA errors by checking the return status after 
each VISA call is to use the VISA exception event. On sessions where an 
exception event handler is installed and vi_event_exception is enabled, 
the exception event handler is called whenever an error occurs while 
executing an operation. 


The exception-handling model follows the event-handling model for 
callbacks and it uses the same operations as those used for general event 
handling. For example, an application calls vilnstallHandler and 
viEnableEvent to enable exception events. The exception event is like 
any other event in VISA, except that the queueing and suspended handler 
mechanisms are not allowed. 
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When an error occurs for a session operation, the exception handler is 
executed synchronously. That is, the operation that caused the exception 
blocks until the exception handler completes its execution. The exception 
handler is executed in the context of the same thread that caused the 
exception event. 

When invoked, the exception handler can check the error condition and 
instruct the exception operation to take a specific action. It can instruct the 
exception operation to continue normally (by returning vi_success) or to 
not invoke any additional handlers in the case of handler nesting (by 
returning vi_success_nchain). 

As noted, an exception operation blocks until the exception handler 
execution is completed. However, an exception handler sometimes may 
prefer to terminate the program prematurely without returning the control to 
the operation generating the exception. VISA does not preclude an 
applicationfrom using a platform-specific or language-specific exception 
handling mechanism from within the VISA exception handler. 

For example, the C++ try/catch block can be used in an application in 
conjunction with the C++ throw mechanism from within the VISA exception 
handler. When using the C++ try/catch/throw or other exception-handling 
mechanisms, the control will not return to the VISA system. This has several 
important repercussions: 

1 If multiple handlers were installed on the exception event, the 
handlers that were not invoked prior to the current handler will 
not be invoked for the current exception. 

2 The exception context will not be deleted by the VISA system when 
a C++ exception is used. In this case, the application should delete 
the exception context as soon as the application has no more use 
for the context, before terminating the session. An application 
should use the viciose operation to delete the exception context. 

3 Code in any operation (after calling an exception handler) may not 
be called if the handler does not return. For example, local 
allocations must be freed before invoking the exception handler, 
rather than after it. 

One situation in which an exception event will not be generated is in the 
case of asynchronous operations. If the error is detected after the operation 
is posted (i.e., once the asynchronous portion has begun), the status is 
returned normally via the I/O completion event. 


84 


Chapter 4 




Programming with VISA 

Trapping Errors 


However, if an error occurs before the asynchronous portion begins (i.e., the 
error is returned from the asynchronous operation itself), then the exception 
event will still be raised. This deviation is due to the fact that asynchronous 
operations already raise an event when they complete, and this I/O 
completion event may occur in the context of a separate thread previously 
unknown to the application. In summary, a single application event handler 
can easily handle error conditions arising from both exception events and 
failed asynchronous operations. 


Using the You can use the vi_event_exception event as notification that an error 

VI_EVENT_ condition has occurred during an operation invocation. The following table 

EXCEPTION Event describes the vi event exception event attributes. 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

VI ATTR EVENT TYPE 

RO 

Global 

ViEventType 

VI_EVENT_EXCEPTION 

N/A 

VI ATTR STATUS 

RO 

Global 

ViStatus 

N/A 

N/A 

VI ATTR OPER NAME 

RO 

Global 

ViString 

N/A 

N/A 


Example:Exception /* This is an example of how to use exception events 
Events to trap VISA errors. An exception event handler must 

be installed and exception events enabled on all 
sessions where the exception handler is used.*/ 

#include <stdio.h> 

#include <visa.h> 

ViStatus stdcall myExceptionHandler ( 

ViSession vi, 

ViEventType eventType, 

ViEvent context, 

ViAddr usrHandle 

) { 

ViStatus exceptionErrNbr; 
char nameBuffer[256]; 

ViString functionName = nameBuffer; 
char errStrBuffer[256]; 

/* Get the error value from the exception context */ 
viGetAttribute( context, VI ATTR_STATUS, 
SexceptionErrNbr ); 

/* Get the function name from the exception context */ 
viGetAttribute( context, VI_ATTR_OPER_NAME, 
functionName ); 
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errStrBuffer[0] = 0; 

viStatusDesc( vi, exceptionErrNbr, errStrBuffer ); 
printf("ERROR: Exception Handler reports\n" "(%s)\n", 
"VISA function '%s' failed with error 0x%lx\n", 
"functionName, exceptionErrNbr, errStrBuffer ) ; 
return VI^SUCCESS; 

} 

void main(){ 

ViStatus status; 

ViSession drm; 

ViSession vi; 

ViAddr myUserHandle = 0; 

status = viOpenDefaultRM( &drm ); 
if ( status < VI_SUCCESS ) { 

printf( "ERROR: viOpenDefaultRM failed with error = 
0x%lx\n", status ); 
return; 

} 

/* Install the exception handler and enable events for it 
*/ 

status = vilnstallHandler(drm, VI_EVENT_EXCEPTION, 
myExceptionHandler, myUserHandle) ; 
if ( status < VI_SUCCESS ) 

{ 

printf( "ERROR: vilnstallHandler failed with error 
0x%lx\n", status ); 

} 


status = viEnableEvent(drm, VI_EVENT_EXCEPTION, VI_HNDLR, 
VI_NULL); 

if ( status < VI_SUCCESS ) { 

printf( "ERROR: viEnableEvent failed with error 
0x%lx\n", status ); 


} 


/* Generate an error to demonstrate that the handler 
will be called */ 

status = viOpen ( drm, "badVisaName", NULL, NULL, &vi ); 
if ( status < VI_SUCCESS ) { 

printf("ERROR: viOpen failed with error 0x%lx\n" 

"Exception Handler should have been called\n" 
"before this message was printed.\n",status ); 

} 

} 
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Lock Functions 


vi Lock/vi Unlock 
Functions 


Using Locks 

In VISA, applications can open multiple sessions to a VISA resource 
simultaneously. Applications can, therefore, access a VISA resource 
concurrently through different sessions. However, in certain cases, 
applications accessing a VISA resource may want to restrict other 
applications from accessing that resource. 


For example, when an application needs to perform successive write 
operations on a resource, the application may require that, during the 
sequence of writes, no other operation can be invoked through any other 
session to that resource. For such circumstances, VISA defines a locking 
mechanism that restricts access to resources. 

The VISA locking mechanism enforces arbitration of accesses to VISA 
resources on a per-session basis. If a session locks a resource, operations 
invoked on the resource through other sessions either are serviced or are 
returned with an error, depending on the operation and the type of lock used. 

If a VISA resource is not locked by any of its sessions, all sessions have full 
privilege to invoke any operation and update any global attributes. Sessions 
are not required to have locks to invoke operations or update global 
attributes. However, if some other session has already locked the resource, 
attempts to update global attributes or invoke certain operations will fail. 

See descriptions of the individual VISA functions in Chapter 7 - VISA 
Language Reference to determine which would fail when a resource is 
locked. 


The VISA viLock function is used to acquire a lock on a resource. 

viLock ( vi, lockType, timeout, requestedKey, accessKey) ; 

The vi_attr_rsrc_lock_state attribute specifies the current locking 
state of the resource on the given session, which can be either 
VT_ N °_ L0CK , VI_EXCLUSIVE_LOCK, or VI_SHARED_LOCK. 

The VISA viUnlock function is then used to release the lock on a resource. 
If a resource is locked and the current session does not have the lock, the 
error vi error rsrc locked is returned. 
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VISA Lock Types 


VISA defines two different types of locks: Exclusive Lock and Shared Lock. 

■ Exclusive Lock - A session can lock a VISA resource using the lock 
type vi_exclusive_lock to get exclusive access privileges to the 
resource. This exclusive lock type excludes access to the resource 
from all other sessions. 

If a session has an exclusive lock, other sessions cannot modify 
global attributes or invoke operations on the resource. However, the 
other sessions can still get atttributes. 

■ Shared Lock - A session can share a lock on a VISA resource with 
other sessions by using the lock type vi_shared_lock. Shared 
locks in VISA are similar to exclusive locks in terms of access 
privileges, but can still be shared between multiple sessions. 

If a session has a shared lock, other sessions that share the lock 
can also modify global attributes and invoke operations on the 
resource (of course, unless some other session has a previous 
exclusive lock on that resource). A session that does not share the 
lock will lack these capabilities. 

Locking a resource restricts access from other sessions and, in the case 
where an exclusive lock is acquired, ensures that operations do not fail 
because other sessions have acquired a lock on that resource. Thus, locking 
a resource prevents other, subsequent sessions from acquiring an exclusive 
lock on that resource. Yet, when multiple sessions have acquired a shared 
lock, VISA allows one of the sessions to acquire an exclusive lock along with 
the shared lock it is holding. 

Also, VISA supports nested locking. That is, a session can lock the 
same VISA resource multiple times (for the same lock type) via multiple 
invocations of the viLock function. In such a case, unlocking the resource 
requires an equal number of invocations of the viUnlock function. Nested 
locking is also explained in detail later in this section. 

Some VISA operations may be permitted even when there is an exclusive 
lock on a resource, or some global attributes may not be read when there is 
any kind of lock on the resource. These exceptions, when applicable, are 
mentioned in the descriptions of the individual VISA functions and attributes. 

See Chapter 1 - VISA Language Reference for descriptions of individual 
functions to determine which are applicable for locking and which are not 
restricted by locking. 
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Example: Exclusive 
Lock 


This example shows a session gaining an exclusive lock to perform the 
viPrintf and viScanf VISA operations on a GPIB device. It then 
releases the lock via the viUnlock function. 

/* lockexcl.c 

This example program queries a GPIB device for an 
identification string and prints the results. Note 
that you may need to change the address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
char buf [256] = {0}; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM (&defaultRM); 

viOpen (defaultRM, "GPIBO::22::INSTR", VI_NULL,VI_NULL, 
&vi) ; 

/* Initialize device */ 
viPrintf (vi, "*RST\n"); 

/* Make sure no other process or thread does anything 
to this resource between viPrintf and viScanf calls */ 

viLock (vi, VI_EXCLUSIVE_LOCK, 2000, VI_NULL, 

VI_NULL); 

/* Send an *IDN? string to the device */ 
viPrintf (vi, "*IDN?\n"); 

/* Read results */ 
viScanf (vi, "%t", &buf); 

/* Unlock this session so other processes and threads 
can use it */ 
viUnlock (vi); 

/* Print results */ 

printf ("Instrument identification string: %s\n", 
buf) ; 

/* Close session */ 
viClose (vi); 
viClose (defaultRM);} 
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This example shows a session gaining a shared lock with the accessKey 
called lockkey. Other sessions can now use this accessKey in the 
requestedKey parameter of the viLock function to share access on the 
locked resource. This example then shows the original session acquiring an 
exclusive lock while maintaining its shared lock. 

When the session holding the exclusive lock unlocks the resource via the 
viUnlock function, all the sessions sharing the lock again have all the 
access privileges associated with the shared lock. 

/* lockshr.c 

This example program queries a GPIB device for an 
identification string and prints the results. Note 
that you must change the address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
char buf [256] = {0}; 
char lockkey [256] = {0}; 

/* Open session to GPIB device at address 22 */ 

viOpenDefaultRM (&defaultRM); 

viOpen (defaultRM, "GPIBO::22::INSTR", 

VIJNIULL, VIJNIULL, &vi) ; 

/* acquire a shared lock so only this process and 
processes 

that we know about can access this resource */ 
viLock (vi, VI_SHAREDJLOCK, 2000, VIJNIULL, lockkey); 

/* at this time, we can make 'lockkey' available to 
other processes that we know about. This can be done 
with shared memory or other inter-process communication 
methods. These other processes can then call 
"viLock(vi,VI SHARED LOCK, 2000, lockkey, lockkey)" 
and they will also have access to this resource. */ 

/* Initialize device */ 
viPrintf (vi, "*RST\n"); 
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/* Make sure no other process or thread does anything 
to this resource between the viPrintfO and the 
viScanf()calls Note: this also locks out the processes 
with which we shared our 'shared lock' key. */ 

viLock (vi, VI_EXCLUSIVE_LOCK, 2000, VI_NULL, VI_NULL) ; 
/* Send an *IDN? string to the device */ 
viPrintf (vi, "*IDN?\n"); 

/* Read results */ 
viScanf (vi, "%t", &buf); 

/* unlock this session so other processes and threads 
can use it */ 
viUnlock (vi) ; 

/* Print results */ 

printf ("Instrument identification string: %s\n", 
buf) ; 

/* release the shared lock also*/ 
viUnlock (vi); 

/* Close session */ 
viClose (vi); 
viClose (defaultRM) ; 
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Programming via GPIB and VXI 


VISA supports three interfaces you can use to access GPIB and VXI 
instruments: GPIB, VXI, and GPIB-VXI. This chapter provides information to 
program GPIB and VXI devices via the GPIB, VXI or GPIB-VXI interfaces, 
including: 

■ GPIB and VXI Interfaces Overview 

■ Using High-Level Memory Functions 

■ Using Low-Level Memory Functions 

■ Using High/Low-Level Memory I/O Methods 

■ Using the Memory Access Resource 

■ Using VXI-Specific Attributes 

See Chapter 4 - Programming with VISA for general information on VISA 
programming for the GPIB, VXI, and GPIB-VXI interfaces. See Chapter 7 - 
VISA Language Reference for information on the specific VISA functions. 
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What is an 10 
Interface? 


VXI Device Types 


GPIB and VXI Interfaces Overview 

This section provides an overview of the GPIB, GPIB-VXI, and VXI 
interfaces, including: 

■ General Interface Information 

■ GPIB Interfaces Overview 

■ VXI Interfaces Overview 

■ GPIB-VXI Interfaces Overview 

General Interface Information 

VISA supports three interfaces you can use to access instruments or 
devices: GPIB, VXI, and GPIB-VXI. The GPIB interface can be used to 
access VXI instruments via a Command Module. In addition, the VXI 
backplane can be directly accessed with the VXI or GPIB-VXI interfaces. 


An 10 interface can be defined as both a hardware interface and as a 
software interface. The 10 Config utility is used to associate a unique 
interface name with a hardware interface. The 10 Libraries use an Interface 
Name or Logical Unit Number to identify an interface. This information is 
passed in the parameter string of the viOpen function call in a VISA 
program. 

10 Config assigns an Interface Name and Logical Unit Number to the 
interface hardware, and other necessary configuration values for an 
interface when the interface is configured. See the Agilent 10 Libraries 
Installation and Configuration Guide for Windows for 10 Config information. 


When using GPIB-VXI or VXI interfaces to directly access the VXI backplane 
(in the VXI mainframe), you must know whether you are programming a 
message-based ora register-based VXI device (instrument). 

A message-based VXI device has its own processor that allows it to 
interpret high-level commands such as Standard Commands for 
Programmable Instruments (SCPI). When using VISA, you can place the 
SCPI command within your VISA output function call. Then, the message- 
based device interprets the SCPI command. In this case you can use the 
VISA formatted I/O or non-formatted I/O functions and program the 
message-based device as you would a GPIB device. 
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However, if the message-based device has shared memory, you can access 
the device's shared memory by doing register peeks and pokes. VISA 
provides two different methods you can use to program directly to the 
registers: high-level memory functions or low-level memory functions. 

A register-based VXI device typically does not have a processor to interpret 
high-level commands. Therefore, the device must be programmed with 
register peeks and pokes directly to the device's registers. VISA provides 
two different methods you can use to program register-based devices: 
high-level memory functions or low-level memory functions. 

GPIB Interfaces Overview 

As shown in the following figure, a typical GPIB interface consists of a 
Windows PC with one or more GPIB cards (PCI and/or ISA) cards installed 
in the PC and one or more GPIB instruments connected to the GPIB cards 
via GPIB cable. I/O communication between the PC and the instruments is 
via the GPIB cards and the GPIB cable. This figure shows GPIB instruments 
at addresses 3 and 5. 
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Example: GPIB The GPIB interface system in the following figure consists of a Windows PC 

(82350) Interface with two 82350 GPIB cards connected to three GPIB instruments via GPIB 

cables. For this system, the 10 Config utility has been used to assign GPIB 
card #1 a VISA name of “GPIBO” and to assign GPIB card #2 a VISA name 
of “GPIB1”. VISA addressing is as shown in the figure. 


GPIB Interface (82350 PCI GPIB Cards) 


Interface VISA Names Windows PC GPIB Cable GPIB Instruments 


VISA Name 
"GPIBO" 

"GPIB1" 



VISA Addressing 

viOpen (... "GPIB0::5::INSTR"...) 
viOpen (... "GPIB0::3::INSTR"...) 
viOpen (... "GPIB1 ::3::INSTR"...) 


Open IO path to GPIB instrument at address 5 using 82350 Card #1 

Open IO path to GPIB instrument at address 3 using 82350 Card #1 

Open IO path to GPIB instrument at address 3 using 82350 Card #2 
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Example: VXI 
(E8491B) Interfaces 


VXI Interfaces Overview 

As shown in the following figure, a typical VXI (E8491) interface consists of 
an E8491 PC Card in a Windows PC that is connected to an E8491B 
IEEE-1394 Module in a VXI mainframe via an IEEE-1394 to VXI cable. The 
VXI mainframe also includes one or more VXI instruments. 



The VXI interface system in the following figure consists of a Windows PC 
with an E8491 PC card that connects to an E8491B IEEE-1394 to VXI 
Module in a VXI Mainframe. For this system, the three VXI instruments 
shown have logical addresses 8, 16, and 24. The 10 Config utility has been 
used to assign the E8491 PC card a VISA name of “VXIO”. VISA addressing 
is as shown in the figure. 

For information on the E8491B module, see the Agilent E8491B User’s 
Guide. For information on VXI instruments, see the applicable VXI 
Instrument User’s Guide. 
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GPIB-VXI Interfaces Overview 

As shown in the following figure, a typical GPIB-VXI interface consists of a 
GPIB card (82350 or equivalent) in a Windows PC that is connected via a 
GPIB cable to an E1406A Command Module. The E1406A sends 
commands to the VXI instruments in a VXI mainframe. There is no direct 
access to the VXI backplane from the PC. 


NOTE 

For a GPIB-VXI interface, VISA uses a DLL supplied by the Command 
Module vendor to translate the VISA VXI calls to Command Module 
commands that are vendor-specific. The DLL required for Agilent/ 
Hewlett-Packard Command Modules is installed by the Agilent 10 
Libraries Installer. This DLL is installed by default when Agilent VISA 
is installed. 


GPIB-VXI (E1406A) Interfaces 


Windows PC GPIB VXI Mainframe 
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Example: GPIB-VXI The GPIB-VXI interface system in the following figure consists of a Windows 
(E1406A) Interface PC with an 82350 GPIB card that connects to an E1406A Command Module 
in a VXI Mainframe. The VXI mainframe includes one or more VXI 
instruments. 

When the 10 Libraries were installed, a GPIB-VXI driver with GPIB address 
9 was also installed and the E1406A was configured for primary address 9 
and logical address (LA) 0. The three VXI instruments shown have logical 
addresses 8, 16, and 24. 

The 10 Config utility has been used to assign the GPIB-VXI driver a VISA 
Name of “GPIB-VXIO” and to assign the 82350 GPIB card a VISA name of 
“GPIBO”. VISA addressing is as shown in the figure. 

For information on the E1406A Command Module, see the Agilent El406A 
Command Module User’s Guide. For information on VXI instruments, see 
the applicable VXI instrument User’s Guide. 



GPIB-VXI Interface (E1406A Command Module) 


Interface VISA Name 


Windows PC 


VXI Mainframe 


VISA Name 
"GPIB-VXIO" 

"GPIBO" 



VISA Addressing 


viOpen (... "GPIB-VXI0::24::INSTR"...) 



Open IO path to VXI instrument at logical address 24 using 
82350 GPIB Card and E1406A VXI Command Module at 


GPIB primary address 9 
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Using High-Level Memory Functions 

High-level memory functions allow you to access memory on the interface 
through simple function calls. There is no need to map memory to a window. 
Instead, when high-level memory functions are used, memory mapping and 
direct register access are automatically done. 

The tradeoff, however, is speed. High-level memory functions are easier to 
use. However, since these functions encompass mapping of memory space 
and direct register access, the associated overhead slows program 
execution time. If speed is required, use the low-level memory functions 
discussed in “Using Low-Level Memory Functions”. 

Programming the Registers 

High-level memory functions include the viin and viOut functions for 
transferring 8-, 16-, or 32-bit values, as well as the viMovein and 
viMoveOut functions for transferring 8-, 16-, or 32-bit blocks of data into 
or out of local memory. You can therefore program using 8-, 16-, or 32-bit 
transfers. 


High-Level Memory This table summarizes the high-level memory functions. 
Functions 


Function 

Description 

viin8 (vi, space, offset, val8) ; 

Reads 8 bits of data from the specified offset. 

viinl6 ( vi, space, offset, vall6) ; 

Reads 16 bits of data from the specified 
offset. 

viin32 (vi, space, offset, val32) ; 

Reads 32 bits of data from the specified 
offset. 

viOut8 ( vi, space, offset, val8) ; 

Writes 8 bits of data to the specified offset. 

viOutl6 (vi, space, offset, vail6) ; 

Writes 16 bits of data to the specified offset. 

viOut32 (vi, space, offset, val32) ; 

Writes 32 bits of data to the specified offset. 

viMovein8 (vi, space, offset, length, buf8) ; 

Moves an 8-bit block of data from the 
specified offset to local memory. 
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Function 

Description 

viMoveinl6 (vi, space, offset, length, buff 6) ; 

Moves a 16-bit block of data from the 
specified offset to local memory. 

viMovein32 (vi, space, offset, length, bu/32) ; 

Moves a 32-bit block of data from the 
specified offset to local memory. 

viMoveOuts (vi, space, offset, length, buffi) ; 

Moves an 8-bit block of data from local 
memory to the specified offset. 

viMoveOutl6 (vi, space, offset, length, buff 6) ,- 

Moves a 16-bit block of data from local 
memory to the specified offset. 

viMoveOut32 (vi, space, offset, length, buf32) ; 

Moves a 32-bit block of data from local 
memory to the specified offset. 


Using viln and When using the viin and viOut high-level memory functions to program to 

viOut the device registers, all you need to specify is the session identifier, address 

space, and the offset of the register. Memory mapping is done for you. For 
example, in this function: 

viin32(w, space, offset, val32); 

vi is the session identifier and offset is used to indicate the offset of the 
memory to be mapped, offset is relative to the location of this device's 
memory in the given address space.The space parameter determines which 
memory location to map the space. Valid space values are: 

■ vi_a16_space - Maps in VXI/MXI A16 address space 

■ vi_a24_space - Maps in VXI/MXI A24 address space 

■ vi_A32_s pace - Maps in VXI/MXI A32 address space 

The val32 parameter is a pointer to where the data read will be stored. 

If, instead, you write to the registers via the viOut32 function, the val32 
parameter is a pointer to the data to write to the specified registers. If the 
device specified by vi does not have memory in the specified address 
space, an error is returned. The following example uses vilnl6. 

ViSession defaultRM, vi; 

ViUIntl6 value; 

viOpenDefaultRM(&&defaultRM); 

viOpen (defaultRM, "VXI::24", VI_NULL, VI_NULL, &vi); 
vilnl6(vi, VI A16 SPACE, 0x100, Svalue); 
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You can also use the viMoveln and viMoveOut high-level memory 
functions to move blocks of data to or from local memory. Specifically, the 
viMoveln function moves an 8-, 16-, or 32-bit block of data from the 
specified offset to local memory, and the viMoveOut functions moves an 
8-, 16-, or 32-bit block of data from local memory to the specified offset. 
Again, the memory mapping is done for you. 

For example, in this function: 

viMoveln32(v/', space, offset, length, buf32); 

vi is the session identifier and offset is used to indicate the offset of the 
memory to be mapped, offset is relative to the location of this device's 
memory in the given address space. The space parameter determines which 
memory location to map the space and the length parameter specifies the 
number of elements to transfer (8-, 16-, or 32-bits). 

The buf32 parameter is a pointer to where the data read will be stored. 

If, instead, you write to the registers via the viMoveOut32 function, the 
buf32 parameter is a pointer to the data to write to the specified registers. 

High-Level Memory Functions Examples 

Two example programs follow that use the high-level memory functions to 
read the ID and Device Type registers of a device at the VXI logical address 
24. The contents of the registers are then printed out. 

The first program uses the VXI interface and the second program accesses 
the backplane with the GPIB-VXI interface. These two programs are 
identical except for the string passed to viOpen. 


This program uses high-level memory functions and the VXI interface to 
read the ID and Device Type registers of a device at VXI0::24. 

/* vxihl.c 

This example program uses the high-level memory 
functions to read the id and device type registers 
of the device at VXI0::24. Change this address if 
necessary. The register contents are then 
displayed.*/ 


#include <visa.h> 
#include <stdlib.h> 
#include <stdio.h> 
void main () { 
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ViSession defaultRM, dmm; 
unsigned short id reg, devtype_reg; 

/* Open session to VXI device at address 24 */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "VXIO::24::INSTR", VI_NULL, VI_NULL, 
&dmm); 

/* Read instrument id register contents */ 
vilnl6(dmm, VI A16 SPACE, 0x00, &id_reg); 

/* Read device type register contents */ 
vilnl6(dmm, VI A16 SPACE, 0x02, &devtype_reg); 

/* Print results */ 

printf ("ID Register = 0x%4X\n", id_reg); 

printf ("Device Type Register = 0x%4X\n", devtype reg) ; 

/* Close sessions */ 
viClose(dmm); 
viClose(defaultRM) ; 


Example: Using the 
GPIB-VXI Interface 
(High-Level) 
Memory Functions 


This program uses high-level memory functions and the GPIB-VXI interface 
to read the ID and Device Type registers of a device at GPIB-VXI0::24. 

/*gpibvxih.c 

This example program uses the high-level memory 
functions 

to read the id and device type registers of the device 
at 

GPIB-VXI0::24. Change this address if necessary. The 
register 

contents are then displayed.*/ 


#include <visa.h> 
#include <stdlib.h> 
#include <stdio.h> 


void main () 

{ 


ViSession defaultRM, dmm; 
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unsigned short id_reg, devtype^reg; 

/* Open session to VXI device at address 24 */ 
viOpenDefaultRM(&defaultRM); 
viOpen(defaultRM, "GPIB-VXIO::24::INSTR" , 
VI_NULL,VI_NULL, &dmm); 

/* Read instrument id register contents */ 
vilnl6(dmm, VI A16 SPACE, 0x00, &id_reg); 

/* Read device type register contents */ 
vilnl6(dmm, VI A16 SPACE, 0x02, &devtype_reg); 

/* Print results */ 

printf ("ID Register = 0x%4X\n", id_reg); 
printf ("Device Type Register = 0x%4X\n", 
devtype_reg); 

/* Close sessions */ 
viClose(dmm); 
viClose(defaultRM); 
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Low-Level Memory 
Functions 


Using Low-Level Memory Functions 

Low-level memory functions allow direct access to memory on the interface 
just as do high-level memory functions. However, with low-level memory 
function calls, you must map a range of addresses and directly access the 
registers with low-level memory functions, such as viPeek.32 and 
viPoke32. 

There is more programming effort required when using low-level memory 
functions. However, the program execution speed can increase. 
Additionally, to increase program execution speed, the low-level memory 
functions do not return error codes. 

Programming the Registers 

When using the low-level memory functions for direct register access, you 
must first map a range of addresses using the viMapAddress function. 
Next, you can send a series of peeks and pokes using the viPeek and 
viPoke low-level memory functions. Then, you must free the address 
window using the viUnmapAddress function. A process you could use is: 

1 Map memory space using viMapAddress. 

2 Read and write to the register's contents using viPeek32 and 
viPoke32. 

3 Unmap the memory space using viUnmapAddress. 

You can program the registers using low-level functions for 8-, 16-, or 32-bit 
transfers. This table summarizes the low-level memory functions. 


Function 

Description 

viMapAddress (vi, mapSpace, 
mapBase, mapSize, access, 
suggested, address) ; 

Maps the specified memory 
space. 

viPeek8 ( vi, addr, val8) ; 

Reads 8 bits of data from address 
specified. 

viPeek!6 (vi, addr, val!6) ; 

Reads 16 bits of data from 
address specified. 
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Function 

Description 

viPeek32 ( vi, addr, val32) ; 

Reads 32 bits of data from 
address specified. 

viPoke8 (vi, addr, val8) ; 

Writes 8 bits of data to address 
specified. 

viPokel6 (vi, addr, vall6) ; 

Writes 16 bits of data to address 
specified. 

viPoke32 (vi, addr, val32) ; 

Writes 32 bits of data to address 
specified. 

viUnmapAddress ( vi) ; 

Unmaps memory space 
previously mapped. 


Mapping Memory 
Space 


viMapAddres s (vi, mapSpace, mapBase, mapSize, access, suggested, 
address ); 

This function maps space for the device specified by the vi session. 
mapBase, mapSize, and suggested are used to indicate the offset of the 
memory to be mapped, amount of memory to map, and a suggested starting 
location, respectively. mapSpace determines which memory location to map 
the space. The following are valid mapSpace choices: 

vi_a16_space - Maps in VXI/MXI A16 address space 
vi_a24_space - Maps in VXI/MXI A24 address space 
vi_a32_space - Maps in VXI/MXI A32 address space 

A pointer to the address space where the memory was mapped is returned 
in the address parameter. If the device specified by vi does not have 
memory in the specified address space, an error is returned. Some example 
viMapAddress function calls are: 

/* Maps to A32 address space */ 

viMapAddress (vi, VI_A32_SPACE, 0x000, 0x100, VI_FALSE, 
VI^NULL,&address); 

/* Maps to A24 address space */ 

viMapAddress(vi, VI_A24_SPACE, 0x00, 0x80, VI_FALSE, 
VI NULL,Saddress); 


When using VISA to access the device's registers, you must map memory 
space into your process space. For a given session, you can have only one 
map at a time. To map space into your process, use the VISA 
viMapAddress function: 
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Reading and Writing 
to Device Registers 


Example: Using 

viPeekl6 


Unmapping Memory 
Space 


Example: Using the 
VXI Interface (Low- 
Level) Memory 
Functions 


When you have mapped the memory space, use the VISA low-level memory 
functions to access the device's registers. First, determine which device 
register you need to access. Then, you need to know the register's offset. 
See the applicable instrument User manual for a description of the registers 
and register locations. You can then use this information and the VISA low- 
level functions to access the device registers. 


An example using viPeekl6 follows. 

ViSession defaultRM, vi; 
ViUIntl6 value; 

ViAddr address; 

ViUIntl6 value; 


viOpenDefaultRM(&&defaultRM); 

viOpen (defaultRM, "VXI: : 24 : : INSTR" , VI_NULL, VI_NULL, 
&vi) ; 

viMapAddress(vi, VI_A16_SPACE, 0x00, 0x04, VI_FALSE, 
VI_NULL, Saddress); 
viPeekl6(vi, addr, Svalue) 

Make sure you use the viUnmapAddress function to unmap the memory 
space when it is no longer needed. Unmapping memory space makes the 
window available for the system to reallocate. 

Low-Level Memory Functions Examples 

Two example programs follow that use the low-level memory functions to 
read the ID and Device Type registers of the device at VXI logical address 
24. The contents of the registers are then printed out. The first program uses 
the VXI interface and the second program uses the GPIB-VXI interface to 
access the VXI backplane. These two programs are identical except for the 
string passed to viOpen. 


This program uses low-level memory functions and the VXI interface to read 
the ID and Device Type registers of a device at VXI0::24. 

/*vxill. c 

This example program uses the low-level memory 
functions to read the id and device type registers 
of the device at VXI0::24. Change this address if 
necessary. The register contents are then displayed.*/ 
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#include <visa.h> 

#include <stdlib.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, dmm; 

ViAddr address; 

unsigned short id^reg, devtype_reg; 

/* Open session to VXI device at address 24 */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "VXIO::24::INSTR", VI_NULL, 

VI_NULL, &dmm); 

/* Map into memory space */ 

viMapAddress(dmm, VI A16_SPACE, 0x00, 0x10, 

VI_FALSE,VI_NULL, Saddress); 

/* Read instrument id register contents */ 
viPeekl6(dmm, address, &id_reg); 

/* Read device type register contents */ 

/* ViAddr is defined as a void so we must cast 
/* it to something else to do pointer arithmetic */ 
viPeekl6(dmm, (ViAddr)((ViUIntl6 *)address + 0x01), 
&devtype_reg); 

/* Unmap memory space */ 
viUnmapAddress(dmm); 

/* Print results */ 

printf ("ID Register = 0x%4X\n", id^reg); 

printf ("Device Type Register = 0x%4X\n", devtype reg); 

/* Close sessions */ 
viClose(dmm); 
viClose(defaultRM); 
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Example: Using the 
GPIB-VXI Interface 
(Low-Level) Memory 
Functions 


This program uses low-level memory functions and the GPIB-VXI interface 
to read the ID and Device Type registers of a device at GPIB-VXI0::24. 

/*gpibvxil.c 

This example program uses the low-level memory 
functions to read the id and device type registers 
of the device at GPIB-VXIO::24. Change this address 
if necessary. Register contents are then displayed.*/ 

#include <visa.h> 

#include <stdlib.h> 

#include <stdio.h> 
void main () { 

ViSession defaultRM, dmm; 

ViAddr address; 

unsigned short id_reg, devtype_reg; 

/* Open session to VXI device at address 24 */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "GPIB-VXIO::24::INSTR", VI_NULL, 
VI_NULL,&dmm); 

/* Map into memory space */ 

viMapAddress(dmm, VI_A16_SPACE, 0x00, 0x10, VI^FALSE, 
VI_NULL, Saddress); 

/* Read instrument id register contents */ 
viPeekl6(dmm, address, &id_reg); 

/* Read device type register contents */ 

/* ViAddr is defined as a void * so we must cast 
/* it to something else to do pointer arithmetic */ 
viPeekl6(dmm, (ViAddr)((ViUIntl6 *)address + 0x01), 
&devtype_reg); 

/* Unmap memory space */ 
viUnmapAddress(dmm); 

/* Print results */ 

printf ("ID Register = 0x%4X\n", id_reg); 

printf ("Device Type Register = 0x%4X\n", devtype reg); 

/* Close sessions */ 

viClose(dmm); 

viClose(defaultRM);} 
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Using Low/High-Level Memory I/O Methods 

VISA supports three different memory I/O methods for accessing memory 
on the VXI backplane, as shown. All three of these access methods can be 
used to read and write VXI memory in the A16, A24, and A32 address 
spaces. The best method to use depends on the VISA program 
characteristics. 

■ Low-level viPeek/viPoke 

□ viMapAddress 

□ viUnmapAddress 

□ viPeek8, viPeekl6, viPeek32 

□ viPoke8, viPokel6, viPoke32 

■ High-level viln/viOut 

□ viln8, vilnl6, viln32 

□ viOut8, viOutl6, viOut32 

■ High-level viMoveln/viMoveOut 

□ viMoveIn8, viMoveInl6, viMoveIn32 

□ viMoveOut8, viMoveOutl6, viMoveOut32 

Using Low-Level viPeek/viPoke 

Low-level viPeek/viPoke is the most efficient in programs that require 
repeated access to different addresses in the same memory space. 

The advantages of low-level viPeek/viPoke are: 

■ Individual viPeek/viPoke calls are faster than viln/viOut or 
viMoveln/viMoveOut calls. 

■ Memory pointer may be directly dereferenced in some cases for the 
lowest possible overhead. 

The disadvantages of low-level viPeek/viPoke are: 

■ viMapAddress call is required to set up mapping before 
viPeek/viPoke can be used. 

■ viPeek/viPoke calls do not return status codes. 

■ Only one active viMapAddress is allowed per vi session. 

■ There may be a limit to the number of simultaneous active 
viMapAddress calls per process or system. 
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Using High-level viln/viOut 

High-level viln/viOut calls are best in situations where a few widely 
scattered memory access are required and speed is not a major 
consideration. 

The advantages high-level viln/viOut are: 

■ Simplest method to implement. 

■ No limit on number of active maps. 

■ A16, A24, and A32 memory access can be mixed in a single vi 
session. 

The disadvantage of high-level viln/viOut calls is that they are slower 
than viPeek/viPoke. 

Using High-level viMoveln/viMoveOut 

High-level viMoveln/viMoveOut calls provide the highest possible 
performance for transferring blocks of data to or from the VXI backplane. 
Although these calls have higher initial overhead than the viPeek/viPoke 
calls, they are optimized on each platform to provide the fastest possible 
transfer rate for large blocks of data. 

For small blocks, the overhead associated with viMoveln/voMoveOut 
may actually make these calls longer than an equivalent loop of viin/ 
viOut calls. The block size at which viMoveln/viMoveOut becomes 
faster depends on the particular platform and processor speed. 

The advantages of high-level viMoveln/viMoveOut are: 

■ Simple to use. 

■ No limit on number of active maps. 

■ A16, A24, and A32 memory access can be mixed in a single vi 
session. 

■ Provides the best performance when transferring large blocks of 
data. 

■ Supports both block and FIFO mode. 

The disadvantage of viMoveln/viMoveOut calls is that they have higher 
initial overhead than viPeek/viPoke. 
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Example: Using VXI 
Memory I/O 


This program demonstrates using various types of VXI memory I/O. 

/* memio.c 

This example program demonstrates the use of various 
memory I/O methods in VISA. */ 

#include <visa.h> 

#include <stdlib.h> 

#include <stdio.h> 

#define VXI^INST "VXIO::24::INSTR" 

void main () { 

ViSession defaultRM, vi; 

ViAddr address; 

ViUIntl6 accessMode; 

unsigned short *memPtrl6; 
unsigned short id_reg; 
unsigned short devtype reg; 
unsigned short memArray[2]; 

/*Open default resource manager and session to instr*/ 
viOpenDefaultRM (&defaultRM); 

viOpen (defaultRM, VXI_INST, VI_NULL,VI_NULL, &vi); 


/* 


Low level memory I/O = viPeekl6 
dereference (when allowed) 


direct memory 


*/ 


/* Map into memory space */ 

viMapAddress (vi, VI_A16_SPACE, 0x00, 0x10, VI_FALSE, 
VI NULL, Saddress); 


/* ================================================= 

Using viPeek 

================================================*/ 


Read instrument id register contents */ 
viPeekl6 (vi, address, &id_reg); 

/* Read device type register contents 

ViAddr is defined as a (void *) so we must cast it 

to something else in order to do pointer arithmetic. */ 
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viPeekl6 (vi, (ViAddr)((ViUIntl6 *)address + 0x01), 
&devtype_reg); 

/* Print results */ 

printf (" viPeekl6: ID Register = 0x%4X\n", id reg); 

printf (" viPeekl6: Device Type Register = 0x%4X\n", 

devtype^reg); 

/* Use direct memory dereferencing if supported */ 
viGetAttribute( vi, VI_ATTR_WIN_ACCESS, SaccessMode ); 
if ( accessMode == VI_DEREF_ADDR ) { 

/* assign pointer to variable of correct type */ 
memPtrl6 = (unsigned short *)address; 

/* do the actual memory reads */ 
id^reg = *memPtrl6; 

devtype_reg = *(memPtrl6+1); 

/* Print results */ 

printf ("dereference: ID Register = 0x%4X\n", 
id_reg); 

printf ("dereference: Device Type Register = 0x%4X\n", 
devtype_reg); 


/* Unmap memory space */ 
viUnmapAddress (vi); 

/*================================================ 

High Level memory I/O = vilnl6 
================================================= */ 


/* Read instrument id register contents */ 
vilnl6 (vi, VI_A16_SPACE, 0x00, &&id_reg); 

/* Read device type register contents */ 
vilnl6 (vi, VI A16 SPACE, 0x02, &devtype_reg); 

/* Print results */ 

printf (" vilnl6: ID Register = 0x%4X\n", id_reg); 

printf (" vilnl6: Device Type Register = 0x%4X\n", 

devtype_reg); 
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/ * ==================================================== 

High Level block memory I/O = viMoveIn!6 

The viMoveln/viMoveOut commands do both block read/ 
write and FIFO read write. These commands offer the 
best performance for reading and writing large data 
blocks on the VXI backplane. For this example we are 
only moving 2 words at a time. Normally, these 
functions would be used to move much larger blocks of data . 

If the value of VI_ATTR_SRC_INCREMENT is 1 (the 
default),viMoveln does a block read. If the value of 
VI_ATTR_SRC_INCREMENT is 0, viMoveln does a FIFO read. 
If the value of VI_ATTR_DEST_INCREMENT is 1 (the default), 
viMoveOut does a block write. If the value of 
VI_ATTR_DEST_INCREMENT is 0, viMoveOut does a FIFO write. 
======================================================== * / 


/* Demonstrate block read. 

Read instrument id register and device type register 
into an array.*/ 

viMoveInl6 (vi, VI A16 SPACE, 0x00, 2, memArray); 

/* Print results */ 

printf (" viMoveInl6: ID Register = 0x%4X\n", 
memArray[0]); 

printf (" viMoveInl6: Device Type Register = 0x%4X\n", 
memArray[1]) ; 

/* Demonstrate FIFO read. 

First set the source increment to 0 so we will 
repetitively read from the same memory location.*/ 
viSetAttribute( vi, VI_ATTR_SRC_INCREMENT, 0 ); 

/* Do a FIFO read of the Id Register */ 
viMoveInl6 (vi, VI A16 SPACE, 0x00, 2, memArray); 

/* Print results */ 

printf (" viMoveInl6: 1 ID Register = 0x%4X\n", 
memArray[0]); 

printf (" viMoveInl6: 2 ID Register = 0x%4X\n", 
memArray[1]); 

/* Close sessions */ 
viClose (vi); 
viClose (defaultRM); } 
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High-Level Memory 
I/O Services 


Low-Level Memory 
I/O Services 


Using the Memory Access Resource 

For VISA 1.1 and later, the Memory Access (MEMACC) Resource type has 
been added to VXI and GPIB-VXI. VXLMEMACC and GPIB-VXI::MEMACC 
allow access to all of the A16, A24, and A32 memory by providing the 
controller with access to arbitrary registers or memory addresses on 
memory-mapped buses. 

The MEMACC resource, like any other resource, starts with the basic 
operations and attributes of other VISA resources. For example, modifying 
the state of an attribute is done via the the operation viSetAttribute 
(see Appendix B - VISA Resource Classes for details). 

Memory I/O Services 

Memory I/O services include high-level memory I/O services and low-level 
memory I/O services. 


High-level Memory I/O services allow register-level access to the interfaces 
that support direct memory access, such as the VXIbus, VMEbus, MXIbus, 
or even VME or VXI memory through a system controlled by a GPIB-VXI 
controller. A resource exists for each interface to which the controller has 
access. 

You can access memory on the interface bus through operations such as 
vilnl6 and viOutl6. These operations encapsulate the map/unmap and 
peek/poke operations found in the low-level service. There is no need to 
explicitly map the memory to a window. 


Low-level Memory I/O services also allow register-1 eve I access to the 
interfaces that support direct memory access. Before an application can use 
the low-level service on the interface bus, it must map a range of addresses 
using the operation viMapAddress. 

Although the resource handles the allocation and operation of the window, 
the programmer must free the window via viUnMapAddress when finished. 
This makes the window available for the system to reallocate. 
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Example: MEMACC 
Resource Program 


This program demonstrates one way to use the MEMACC resource to open 
the entire VXI A16 memory and then calculate an offset to address a specific 
device. 

/* peekl6.c */ 

#include <stdio.h> 

#include <stdlib.h> 

#include <visa.h> 


#define EXIT 1 
#define NO EXIT 0 


/* This function simplifies checking for VISA errors. */ 
voidcheckError( ViSession vi, ViStatusstatus, char*errStr, 
int doexit){ 

char buf[256]; 
if (status >= VI^SUCCESS) 
return; 
buf[0] = 0; 

viStatusDesc( vi, status, buf ); 

printf( "ERROR 0x%lx (%s)\n '%s'\n", status, errStr, 
buf ) ; 

if ( doexit == EXIT ) 
exit ( 1 ); 

} 


void main() 
ViSession 
ViSession 
ViUIntl6 
ViUIntl6 
ViUInt8 
ViUIntl6 
ViStatus 
ViUIntl6 


{ 

drm; 

vi; 

inDatal6 = 
peekDatal6 
*addr; 
*addrl6; 
status; 
offset; 


0 ; 


= 0 ; 


status = viOpenDefaultRM ( &drm ); 

checkError( 0, status, "viOpenDefaultRM", EXIT ); 

/* Open a session to the VXI MEMACC Resource*/ 
status = viOpen ( drm, "vxiO:rmemacc", VI NULL, VI NULL, 
&vi ) ; 

checkError (0, status, "viOpen", EXIT ); 
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/* Calculate the A16 offset of the VXI REgisters for the 
device at VXI logical address 8. */ 
offset = OxcOOO + 64 * 8; 

/* Open a map to all of A16 memory space. */ 
status = viMapAddress(vi,VI A16 SPACE,0,0x10000, 
VI_FALSE,0,(ViPAddr)(&addr)); 
checkError( vi, status, "viMapAddress", EXIT ); 

/* Offset the address pointer retruned from 
viMapAddress for use with viPeekl6. */ 
addrl6 = (ViUIntl6 *) (addr + offset); 

/* Peek the contents of the card's ID register (offset 0 
from card's base address. Note that viPeek does not 
return a status code. */ 
viPeek!6( vi, addrl6, &peekDatal6 ); 

/* Now use vilnl6 and read the contents of the same 
register */ 

status = vilnl6(vi, VI_A16_SPACE, 

(ViBusAddress)offset, 

&inDatal6 ); 

checkError(vi, status, "vilnl6", NO EXIT ); 

/* Print the results. */ 

printf( "inDatal6 : 0x%04hx\n", inDatal6 ); 
printf( "peekDatal6: ox%04hx\n", peekDatal6 ); 

viClose ( vi ); 
viClose (drm ); 
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MEMACC Attribute Descriptions 


Generic MEMACC The following Read Only attributes (vi_attr_tmo_value is Read/Write) 
Attributes provide general interface information. 


Attribute 

Description 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout 
value of vi tmo immediate means operation should 
never wait for the device to respond. A timeout value of 
vi tmo infinite disables the timeout mechanism. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI_ATTR_DMA_ALLOW_EN 

Specifies whether I/O accesses should use DMA (vi true) or 
Programmed I/O (vi false). 


VXI and GPIB-VXI The following attributes, most of which are read/write, provide memory 
Specific MEMACC window control information. 

Attributes 


Attribute 

Description 

VI ATTR VXI LA 

Logical address of the local controller. 

VI ATTR SRC INCREMENT 

Used in viMoveinxx operation to specify how much the 
source offset is to be incremented after every transfer. The 
default value is 1 and the viMoveinxx operation moves 
from consecutive elements. 

If this attribute is set to 0, the viMoveinxx operation will 
always read from the same element, essentially treating the 
source as a FIFO register. 
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Attribute 

Description 

VI ATTR DEST INCREMENT 

Used in viMoveOutxx operation to specify how much the 
destination offset is to be incremented after every transfer. 
The default value is 1 and the viMoveOutxx operation 
moves into consecutive elements. 

If this attribute is set to 0, the viMoveOutxx operation will 
always write to the same element, essentially treating the 
destination as a FIFO register. 

VI ATTR WIN ACCESS 

Specifies modes in which the current window may be 
addressed: not currently mapped, through the viPeekxxor 
viPokexx operations only, or through operations and/or by 
directly de-referencing the address parameter as a pointer. 

VI ATTR WIN BASE ADDR 

Base address of the interface bus to which this window is 
mapped. 

VI ATTR WIN SIZE 

Size of the region mapped to this window. 

VI ATTR SRC BYTE ORDER 

Specifies the byte order used in high-level access 
operations, such as viinxxand viMoveinxx, when 
reading from the source. 

VI ATTR DEST BYTE ORDER 

Specifies the byte order used in high level access 
operations, such as viOutxx and viMoveOutxx, when 
writing to the destination. 

VI ATTR WIN BYTE ORDER 

Specifies the byte order used in low-level access 
operations, such as viMapAddress, viPeekxx, and 
viPokexx, when accessing the mapped window. 

VI ATTR SRC ACCESS PRIV 

Specifies the address modifier used in high-level access 
operations, such as viinxx and viMoveinxx, when reading 
from the source. 

VI ATTR DEST ACCESS PRIV 

Specifies address modifier used in high-level access 
operations such as viOutxx and viMoveOutxx, when 
writing to destination. 

VI ATTR WIN ACCESS PRIV 

Specifies address modifier used in low-level access 
operations, such as viMapAddress , viPeekxx, and 
viPokexx, when accessing the mapped window. 
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GPIB-VXI Specific The following Read Only attributes provide specific address information 
MEMACC Attributes about GPIB hardware. 


Attribute 

Description 

VI ATTR INTF PARENT NUM 

Board number of the GPIB board to which the GPIB-VXI is 
attached. 

VI ATTR GPIB PRIMARY ADDR 

Primary address of the GPIB-VXI controller used by the 
session. 

VI ATTR GPIB SECONDARY ADD 

R 

Secondary address of the GPIB-VXI controller used by 
the session. 


MEMACC Resource The following Read Only events provide notification that an asynchronous 
Event Attribute operation has completed. 


Attribute 

Description 

VI ATTR EVENT TYPE 

Unique logical identifier of the event. 

VI ATTR STATUS 

Return code of the asynchronous I/O operation that has 
completed. 

VI ATTR JOB ID 

Job ID of the asynchronous I/O operation that has 
completed. 

VI ATTR BUFFER 

Address of a buffer used in an asynchronous operation. 

VI ATTR RET COUNT 

Actual number of elements that were asynchronously 
transferred. 
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Using VXI-Specific Attributes 

VXI specific attributes can be useful to determine the state of your VXI 
system. Attributes are read only and read/write. Read only attributes specify 
things such as the logical address of the VXI device and information about 
where your VXI device is mapped, this section shows how you might use 
some of the VXI specific attributes. See Appendix B - VISA Resource 
Classes for information on VISA attributes. 

Using the Map Address as a Pointer 

The vi_attr_win_access read-only attribute specifies how a window 
can be accessed. You can access a mapped window with the VISA low-level 
memory functions or with a C pointer if the address is de-referenced. To 
determine how to access the window, read the vi_attr_win_access 
attribute. 

vi_attr_win_ The vi_attr_win_access read-only attribute can be set to one of the 
ACCESS Settings following: 


Setting 

Description 

VI_NMAPPED 

Specifies that the window is not mapped. 

VI_USE_OPERS 

Specifies that the window is mapped and you can 
only use the low-level memory functions to access 
the data. 

VI_DEREF_ADDR 

Specifies that the window is mapped and has a de¬ 
referenced address. In this case you can use the 
low-level memory functions to access the data, or 
you can use a C pointer. Using a de-referenced C 
pointer will allow faster access to data. 
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Example: 
Determining 
Window Mapping 


This example shows how you can read the vi_attr_win_access 
attribute and use the result to determine how to access memory. 

ViAddr address; 

ViUIntl6 access; 

ViUIntl6 value; 


viMapAddress(vi, VI_A16_SPACE, 0x00, 0x04, VI_FALSE, 
VI_NULL, Saddress); 

viGetAttribute(vi, VI ATTR_WIN_ACCESS, Saccess); 


If(access==VI_USE_OPERS) { 

viPeekl6(vi, (ViAddr)(((ViUIntl6 *)address) + 
4/sizeof(ViUIntl6)), Svalue) 

}else if (access==VI DEREF ADDR){ 

value=*((ViUIntl6 *)address+4/sizeof(ViUIntl6)); 
}else if (access==VI_NMAPPED) { 
return error; 

} 
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Setting the VXI Trigger Line 

The vi_attr_trig_id attribute is used to set the VXI trigger line. This 
attribute is listed under generic attributes and defaults to vi_trig_sw 
(software trigger). To set one of the VXI trigger lines, set the 
vi_attr_trig_id attribute as follows: 

viSetAttribute(w, VI_ATTR_TRIG_ID, VI_TRIG_TTLO); 

The above function sets the VXI trigger line to TTL trigger line 0 
(vi_trig_ttlO). The following are valid VXI trigger lines. (Panel In is an 
Agilent extension of the VISA specification.) 


VXI Trigger Line 

VI_ATTR_TRIG_ID Value 

TTL 0 

VI_TRIG_TTLO 

TTL 1 

VI_TRIG_TTLl 

TTL 2 

VI_TRIG_TTL2 

TTL 3 

VI_TRIG_TTL3 

TTL 4 

VI_TRIG_TTL4 

TTL 5 

VI_TRIG_TTL5 

TTL 6 

VI_TRIG_TTL6 

TTL 7 

VI_TRIG_TTL7 

ECL 0 

VI_TRIG_ECLO 

ECL 1 

VI_TRIG_ECLl 

Panel In 

VI_TRIG_PANEL_IN 


Once you set a VXI trigger line, you can set up an event handler to be called 
when the trigger line fires. See Chapter 4 - Programming with VISA for more 
information on setting up an event handler. Once the vi_event_trig 
event is enabled, the vi_attr_trig_id becomes a read only attribute 
and cannot be changed. You must set this attribute prior to enabling event 
triggers. 

The VI_ATTR_TRIG_ID attribute can also be used by viAssertTrigger 
function to assert software or hardware triggers. If vi_attr_trig_id is 
vi_trig_sw, the device is sent a Word Serial Trigger command. If the 
attribute is any other value, a hardware trigger is sent on the line 
corresponding to the value of that attribute. 
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Programming via LAN 


This chapter gives guidelines for programming via a LAN (Local Area 
Network). A LAN is a way to extend the control of instrumentation beyond 
the limits of typical instrument interfaces. The chapter contents are: 

■ LAN Interfaces Overview 

■ Communicating with GPIB Devices via LAN 


NOTE 

This chapter does not describe programming using the VISA TCPIP 
Interface Type. To use GPIB over the LAN, you must first configure the 
TCPIP:LAN Client interface and then the VISA LAN Client during Agilent 
10 Libraries configuration. 

The TCPIP VISA interface type can be used directly to communicate with 
GPIB devices over LAN, without having to configure a VISA LAN Client. 

See the Agilent 10 Libraries Installation and Configuration Guide for 
Windows for LAN installation information and to start or stop the LAN 
servers. 
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LAN Interfaces Overview 

This section provides an overview of LAN (Local Area Network) interfaces. 
A LAN is a way to extend the control of instrumentation beyond the limits of 
typical instrument interfaces. To communicate over the LAN, you must first 
configure the LAN Client interface. There are three main types of LAN 
interfaces: 

■ LAN Client 

■ VISA LAN Client 

■ LAN Server 

LAN Hardware Architecture 

The LAN software provided with the Agilent 10 Libraries allows 
instrumentation control over a LAN. Using standard LAN connections, 
instruments can be controlled from computers that do not have special 
interfaces for instrument control. 


Client/Server Model The LAN software uses the client/server model of computing. Client/server 
computing refers to a model where an application (the client) does not 
perform all necessary tasks of the application itself. Instead, the client 
makes requests of another computing device (the server) for certain 
services. 

As shown in the following figure, a LAN client (such as a Series 700 HP-UX 
workstation or a Windows 95/98/Me/NT/2000 PC) makes VISA requests 
over the network to a LAN server (such as a Series 700 HP-UX workstation, 
a Windows 95/98/Me/NT/2000 PC, or an E2050 LAN/GPIB Gateway). 


Gateway Operation The LAN server is connected to the instrumentation or devices to be 

controlled. Once the LAN server has completed the requested operation on 
the instrument or device, the LAN server sends a reply to the LAN client. 
This reply contains requested data and status information that indicates 
whether or not the operation was successful. The LAN server acts as a 
gateway between the LAN software that the client system supports and the 
instrument-specific interface that the device supports. 
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Series 700 PCs or Windows 95/98/Me/2000/NT PCs 


Client 



LAN 


Server 


Series 700 PCs or 
Windows 95/98/Me/ 
2000/NT PCs 


GPIB bus 
(or other) 


E2050 

LAN/GPIB 

Gateway 


l) 




GPIB 

bus 


GPIB LAN Instruments 

Instrument (VXI-11.2 GPIB Emulation 

or 

VXI-11.3 LAN Instruments) 


GPIB 

Instruments 
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LAN Software Architecture 

An 10 interface can be defined as both a hardware interface and as a 
software interface. You can use the 10 Config utility to associate a unique 
interface name with a hardware interface. The 10 Libraries use an Interface 
Name or Logical Unit Number to identify an interface. This information is 
passed in the parameter string of the viOpen function call in a VISA 
program. 

10 Config assigns an Interface Name and Logical Unit Number to the 
interface hardware, as well as other necessary configuration values for an 
interface when the interface is configured. See the Agilent 10 Libraries 
Installation and Configuration Guide for Windows for details on using 10 
Config. 

As shown in the following figure, the client system contains the LAN client 
software and the LAN software (TCP/IP) needed to access the server 
(gateway). The gateway contains the LAN server software, LAN (TCP/IP) 
software, and the instrument driver software needed to communicate with 
the client and to control the instruments or devices connected to the 
gateway. 



Chapter 6 


131 







Programming via LAN 

LAN Interfaces Overview 


The LAN software is built on top of standard LAN networking protocols. 
There are two LAN networking protocols provided with the Agilent 10 
Libraries software. You can use one or both of these protocols when 
configuring your systems (via Agilent 10 Libraries configuration) to use 
VISA over LAN. 

■ SICL-LAN Protocol is a networking protocol developed by Agilent 
that is compatible with all VISA LAN products. This LAN networking 
protocol is the default choice in the Agilent 10 Libraries configuration 
when configuring the LAN client. The SICL-LAN protocol on HP-UX 
10.20, Windows 95/98/Me/2000/NT supports VISA operations over 
LAN to GPIB interfaces. 

■ VXI-11 (TCP/IP Instrument Protocol) is a networking protocol 
developed by the VXIbus Consortium based on the SICL-LAN 
Protocol that permits interoperability of LAN software from different 
vendors who meet the VXIbus Consortium standards. 

When using either of these networking protocols, the LAN software uses the 
TCP/IP protocol suite to pass messages between the LAN client and the 
LAN server. The server accepts device I/O requests over the network from 
the client and then proceeds to execute those I/O requests on a local 
interface (GPIB, etc.). 

By default, the LAN Client supports both protocols by automatically 
detecting the protocol the server is using. When a VISA viOpen is 
performed, the LAN Client driver first tries to connect using the SICL-LAN 
protocol. If that fails, the driver will try to connect using the VXI-11 protocol. 

If you want to control the protocol used, you can configure more than one 
LAN Client interface and set each interface to a different protocol. The 
protocol used will then depend on the interface you are connecting through. 

Thus, you can have more than one SICL-LAN and one VXI-11 protocols for 
your system. In VISA, the protocol used is determined by the configuration 
settings and cannot be changed programatically. The LAN Client also 
supports TCP/IP socket reads and writes. 

When you have configured VISA LAN Client interfaces, you can then use 
the interface name specified during configuration in a VISA viOpen call of 
your program. However, the LAN server does not support simultaneous 
connections from LAN clients using the SICL-LAN Protocol and from LAN 
clients using VXI-11 (TCP/IP Instrument Protocol). 
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There are three LAN servers that can be used with VISA: the E2050 
LAN/GPIB Gateway, an HP Series 700 computer running HP-UX, or a PC 
running Windows 95/98/Me/2000/NT. To use this capability, the LAN server 
must have a local GPIB interface configured for I/O. 

LAN Client Interface Overview 

There are two main configurations for a LAN Client interface: 

■ LAN Client (Gateway) 

■ LAN Client (LAN) 

This section provides an example of each configuration and shows 
applicable VISA viOpen commands. See Chapter 7 - VISA Language 
Reference for details on the VISA commands. 
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Example: LAN The LAN Client interface system in the following figure consists of a 

Client (Gateway) Windows PC with a LAN card, an E2050 LAN/GPIB gateway, and two GPIB 

Interface instruments. For this system, the 10 Config utility has been used to assign 

the LAN card a VISA name of “TCPIPO”. 

With this name assigned to the interface, VISA addressing is as shown in 
the figure and you can use the VISA viOpen command to open the I/O 
paths to the GPIB instruments as shown in the figure. 


LAN Client (Gateway) 


Interface VISA Names Windows PC LAN/GPIB Gateway GPIB Instruments 


VISA Name 


"TCPIPO" 



VISA Addressing (Using LAN Client) 

viOpen (... "TCPIP0::machine1::hpib,5::INSTR"...) 
viOpen (..."TCPIP0::machine1::hpib,3::INSTR"...) 


Open IO path to GPIB instrument at address 5 
Open IO path to GPIB instrument at address 3 
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Example: LAN 
Client (LAN) 
Interface 


The LAN Client interface system in the following figure consists of a 
Windows PC with a LAN card and three LAN instruments. Instrumentl and 
instrument2 are VXI-11.2 (GPIB Emulation) instruments and instruments is 
a VXI-11.3 LAN instrument. 

For this system, the 10 Config utility has been used to assign the LAN card 
a VISA name of “TCPIPO”. For the addressing examples, instrumentl has 
been addressed by its machine name, instrument 2 has been addressed by 
its IP address, and instruments by its LAN name (instO). 

Since unique names have been assigned by 10 Config, you can now use the 
VISA viOpen command to open the I/O paths to the GPIB instruments as 
shown in the figure. 



Interface VISA Name 


VISA Name 

"TCPIPO" 


LAN Client (LAN) 


Windows PC 


LAN Instruments 



VISA Addressing (Using LAN Client) 

viOpen (... "TCPIP0::instrument1::gpib0,5::INSTR".. 
viOpen (... "TCPIP0::1.2.3.4::gpib0,3::INSTR"...) 
viOpen (... "TCPIP0::instrument3::inst0::INSTR"...) 


Open 10 path to LAN instrument at address 5 
Open 10 path to LAN instrument at address 3 
Open 10 path to LAN instruments 
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VISA LAN Client Interface Overview 

There are two main configurations for a VISA LAN Client interface: 

■ VISA LAN Client (Gateway) 

■ VISA LAN Client (LAN) 

This section provides an example of each configuration and shows 
applicable VISA viOpen commands. See Chapter 7 - VISA Language 
Reference for details on the VISA commands. 


NOTE 

You must install a LAN Client interface BEFORE you can use a VISA LAN 
Client interface. See “Configuring LAN Client Interfaces” for details on 
configuring LAN Client interfaces. 


Example: VISA LAN 
Client (Gateway) 

Interface 

In addition, a VISA LAN Client has been configured with the interface names 
and host names shown in the figure. Also, the E2050 LAN/GPIB Gateway 
has been assigned a name of machinel and an hpib-name = hpib. 

Since unique names have been assigned by 10 Config, you can now use the 
VISA viOpen command to open the I/O paths to the GPIB instruments as 
shown in the figure. 


The VISA LAN Client interface system in the following figure consists of a 
Windows PC with a LAN card, an E2050 LAN/GPIB gateway, and two GPIB 
instruments. The 10 Config utility has been used to assign the LAN card 
a VISA name of “TCPIPO”. 
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VISA LAN Client (Gateway) 


Interface VISA Names Windows PC 


LAN/GPIB Gateway GPIB Instruments 


VISA Name 
"GPIB1" 

"TCPIPO" 



VISA LAN Client Parameters 

"GPIB1” 
"Ian" 

"machinel" 
"hpib" 


VISA Interface Name 
LAN Client SICL Interface Name 
Remote Host Name 
Remote SICL Interface Name 


VISA Addressing (Using LAN Client) 

viOpen (... "TCPIP0::machine1::hpib,5::INSTR"...) °P en 10 P ath to GPIB instrument at address 5 
viOpen (,.."TCPIP0::machine1::hpib,3::INSTR "...) °P en 10 P ath to GPIB instrument at address 3 


VISA Addressing (Using VISA LAN Client) 


viOpen (... "GPIB1 ::5::INSTR"...) 
viOpen (... "GPIB1 ::3::INSTR "...) 


Open IO path to LAN instrument at address 5 
Open IO path to LAN instrument at address 3 
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Example: VISA LAN 
Client (LAN) 

Interface 

For this system, the 10 Config utility has been used to assign the LAN card 
a VISA name of “TCPIPO”. In addition, two VISA LAN Clients have been 
configured with the interface names and host names shown in the figure. 

For the addressing examples, instrumentl has been addressed by its 
machine name, instrument 2 has been addressed by its IP address, and 
instruments by its LAN name (instO). 

Since unique names have been assigned by 10 Config, you can now use the 
VISA viOpen command to open the I/O paths to the GPIB instruments as 
shown in the figure. Note, however, that you cannot talk to instruments with 
VISA LAN Client. You must use the LAN Client to talk to instruments, since 
instruments is not a remote gpib interface. 


The VISA LAN Client interface system in the following figure consists of a 
Windows PC with a LAN card and three LAN instruments. Instrumentl and 
instrument2 are VXI-11.2 (GPIB Emulation) instruments and instruments is 
a VXI-11.3 LAN instrument. 


NOTE 

When using the VXI-11 protocol with VISA LAN Client, the Remote SICL 
Interface Name must be of the form gpibN where N is 0 or a positive 
integer. This restriction does not apply to the SICL-LAN protocol. 
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VISA LAN Client (LAN) 


Interface VISA Names 


VISA Name 


Windows PC 


LAN 


LAN Instruments 


"GPIB1" 


"GPIB2" 


"TCPIPO" 



VISA LAN Client Parameters 

VISA Interface Name 
LAN Client SICL Interface Name 
Remote Host Name 
Remote SICL Interface Name 


GPIB1 

GPIB2 

"GPIB1" 

"GPIB2" 

"Ian” 

"Ian" 

"instrument"!" 

"1.2.3.4" 

"gpibO" 

"gpibO" 


VISA Addressing (Using LAN Client) 


viOpen (... "TCPIP0::instrument1::gpib0,5::INSTR”...) 
viOpen (... ”TCPIP0::1.2.3.4::gpib0,3::INSTR"...) 
viOpen (... ”TCPIP0::instrument3::inst0::INSTR"...) 


Open IO path to LAN instrument at address 5 
Open IO path to LAN instrument at address 3 
Open IO path to LAN instruments 


VISA Addressing (Using VISA LAN Client) 

VISA: viOpen (... "GPIB1 ::5::INSTR"...) 
viOpen (... "GPIB2::3::INSTR ”...) 
Cannot talk to instruments 


Open IO path to LAN instrument at address 5 
Open IO path to LAN instrument at address 3 
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LAN Server Interface Overview 

This section provides an example of the LAN Server interface configuration 
and shows applicable VISA viOpen commands. See Chapter 1 - VISA 
Language Reference for details on the VISA commands. 


Example: LAN The LAN Server interface system in the following figure consists of a 

Server Interface Windows PC acting as a LAN client, a second PC acting as a LAN server, 

and a GPIB instrument. The 10 Config utility has been used to assign the 
LAN card a VISA name of “TCPIPO”. Also, the GPIB card in the LAN server 
PC has been assigned VISA name of “GPIBO”. The LAN server PC has 
been assigned a name of machine2. 

Since unique names have been assigned by 10 Config, you can now use the 
VISA viOpen command to open the I/O paths to the GPIB instruments as 
shown in the figure. 



LAN Server (PC as Server) 


Interface VISA Names 


VISA Name 


LAN Card: "TCPIPO'' 
GPIB Card: "GPIBO" 


Windows PC Windows PC Gp|B | nstrumen t 

(LAN Client) (LAN Server) 


machine2 



VISA Addressing 

viOpen (... "TCPIP0::machine2::hpib7,5::INSTR".) 



Open IO path to GPIB instrument at address 5 
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Communicating with GPIB Devices via LAN 

VISA supports LAN-gatewayed sessions to communicate with configured 
LAN servers. Since the LAN server configuration is determined by the type 
of server present, the only action required by the user is to configure VISA 
for a VISA LAN Client during Agilent 10 Libraries configuration. See the 
Agilent 10 Libraries Installation and Configuration Guide for Windows for 
information on configuring a VISA LAN Client. 


NOTE 

A LAN session to a remote interface provides the same VISA function 
support as if the interface was local, except that all VXI specific functions 
are not supported over LAN. 


Addressing a Session 

In general, the rules to address a LAN session are the same as to address 
a GPIB session. The only difference for a LAN session is that you use the 
VISA Interface Name (provided during I/O configuration) that relates to the 
VISA LAN Client. This example illustrates addressing a GPIB device 
configured over the LAN. 


GPIB0::7::0 


A GPIB device at primary address 7 and secondary 
address 0 on the GPIB interface. This GPIB interface 
(GPIBO) is configured as a VISA LAN Client in the 
Agilent 10 Libraries configuration. 


Example: Opening a This example shows one way to open a device session with a GPIB device 
Device Session at primary address 23. See Chapter 4 - Programming with VISA for more 
information on addressing device sessions. 

ViSession defaultRM, vi;. 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "GPIBO::23::INSTR", VI_NULL, 
VI_NULL,&vi); 


viClose(vi); 
viClose(defaultRM) ; 
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This program opens a session with a GPIB device and sends a comma 
operator to send a comma-separated list. The program is intended to show 
specific VISA functionality and does not include error trapping. Error 
trapping, however, is good programming practice and is recommended in 
your VISA applications. See Chapter 4 - Programming with VISA for 
information on error trapping. 

/*formatio.c 

This example program makes a multimeter measurement 
with a comma-separated list passed with formatted 
I/O and prints the results. Note that you must change 
the device address. */ 

#include <visa.h> 

#include <stdio.h> 

void main () { 

ViSession defaultRM, vi; 
double res; 

double list [2] = {1,0.001}; 

/* Open session to GPIB device at address 22 */ 
viOpenDefaultRM(&defaultRM); 

viOpen(defaultRM, "GPIBO::22::INSTR", VI_NULL, 
VINULL, &vi) ; 

/* Initialize device */ 
viPrintf(vi, "*RST\n"); 

/* Set up device and send comma-separated list */ 
viPrintf(vi, "CALC:DBM:REF 50\n"); 
viPrintf(vi, "MEAS:VOLT:AC? %,2f\n", list); 

/* Read results */ 
viScanf(vi, "%lf", Sres); 

/* Print results */ 

printf ("Measurement Results: %lf\n", res); 

/* Close session */ 
viClose(vi); 
viClose(defaultRM); 
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Using Timeouts over LAN 

The client/server architecture of the LAN software requires the use of two 
timeout values: one for the client and one for the server. 


Client/Server 

Operation 


When the client sends an I/O request to the server, the timeout value 
determined by the values set with the vi_attr_tmo_value attribute is 
passed with the request. The client may also adjust the value sent to the 
server if vi_tmo_infinite was specified. The server will use that timeout 
in performing the I/O operation, just as if that timeout value had been used 
on a local I/O operation. 

If the server's operation is not complete in the specified time, the server will 
send a reply to the client which indicates that a timeout occurred, and the 
VISA call made by the application will return an error. 

When the client sends an I/O request to the server, it starts a timer and 
waits for the reply from the server. If the server does not reply in the time 
specified, the client stops waiting for the reply from the server and returns 
an error. 


The server's timeout value is specified by setting a VISA timeout via the 
vi_attr_tmo_value attribute. The server will also adjust the requested 
value if infinity is requested. The client's timeout value is determined by the 
values set when you configure the LAN Client during the Agilent 10 
Libraries configuration. See the Agilent 10 Libraries Installation and 
Configuration Guide for configuration information. 


LAN Timeout Values The LAN Client configuration specifies two timeout-related configuration 
values for the LAN software. These values are used by the software to 
calculate timeout values. See the Agilent 10 Libraries Installation and 
Configuration Guide for Windows for information on setting these values. 

■ Server Timeout. Timeout value passed to the server when an 
application sets the VISA timeout to infinity (vi_tmo_infinite). 
Value specifies the number of seconds the server will wait for the 
operation to complete before returning an error. If this value is zero 
(0), the server will wait forever. 

■ Client Timeout Delta. Value added to the VISA timeout value 
(server's timeout value) to determine the LAN timeout value 
(client's timeout value). Value specifies the number of seconds. 
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Application 
Terminations and 
Timeouts 


The timeouts are adjusted using the following algorithm: 

■ The VISA Timeout, which is sent to the server for the current call, 
is adjusted if it is currently infinity (vi_tmo_infinite). In that 
case, it will be set to the Server Timeout value. 

■ The LAN Timeout is adjusted if the VISA Timeout plus the Client 
Timeout Delta is greater than the current LAN Timeout. In this case, 
the LAN Timeout is set to the VISA Timeout plus the Client Timeout 
Delta. 

■ The calculated LAN Timeout increases as necessary to meet the 
needs of the application, but never decreases. This avoids the 
overhead of readjusting the LAN Timeout every time the application 
changes the VISA Timeout. 

To change the defaults: 

1 Run the 10 Config utility (Windows) or the visacfg utility 
(HP-UX). 

2 Edit the LAN Client interface. 

3 Change the Server Timeout or Client Timeout Delta parameter. 
(See online help for information on changing these values.) 

4 Restart the VISA LAN applications. 


If an application is killed either via Ctrl+C or the HP-UX kill command 
during a VISA operation performed at the LAN server, the server will 
continue to try the operation until the server's timeout is reached. 

By default, the LAN server associated with an application using a timeout of 
infinity that is killed may not discover that the client is no longer running for 
up to two minutes. (If you are using a server other than the LAN server 
supported with the product, check that server's documentation for its default 
behavior.) 

If both the LAN client and LAN server are configured to use a long timeout 
value, the server may appear "hung." If this situation is encountered, the 
LAN client (via the Server Timeout value) or the LAN server may be 
configured to use a shorter timeout value. 
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Using Signal 
Handling over LAN 
(HP-UX Only) 


If long timeouts must be used, the server may be reset. An HP-UX server 
may be reset by logging into the server host and killing the running 
siclland daemon(s). However, this procedure will affect all clients 
connected to the server. 

A Windows 95, Windows 98, Windows Me, Windows 2000, or Windows 
NT server may be reset by typing Ctrl+C in the LAN Server window and then 
restarting the server from the Agilent 10 Libraries program group. This 
procedure will also affect all clients connected to the server. 

LAN Signal Handling on HP-UX 

This section describes how to use signal handling and service requests over 
LAN for HP-UX. 


VISA uses SIGIO signals for SRQs on LAN interfaces on HP-UX. The 
VISA LAN Client installs a signal handler to catch SIGIO signals. To enable 
sharing of SIGIO signals with other portions of an application, the VISA LAN 
SIGIO signal handler remembers the address of any previously installed 
SIGIO handler and calls this handler after processing a SIGIO signal itself. 

If your application installs a SIGIO handler, it should also remember the 
address of a previously installed handler and call it before completing. The 
signal number used with LAN (SIGIO) cannot be changed. 
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Notes: 
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This chapter describes each function in the VISA library for the Windows 
and HP-UX programming environments and provides an alphabetical list of 
interfaces and Resource Classes associated with each functions. VISA 
functions are listed in alphabetical order. 
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VISA Functions Overview 

This section lists VISA functions by applicable interfaces and resource 
classes, and lists VISA functions by type of operations performed. 

VISA Functions by Interface/Resource 

This table lists VISA functions, supported interfaces (GPIB, VXI, etc.) and 
associated resource classes (INSTR, INTFC, etc.) that are implemented in 
Agilent VISA. 


Interface 

— 

— 

GPIB 

GPIB- 

VXI 

VXI 

TCPIP 

ASRL 

Resource Class 

Find 

List 

Rsrc- 

Mgr 

INSTR 

INTFC 

INSTR 

INSTR 

MEM- 

ACC 

BACK¬ 

PLANE 

INSTR 

SOC¬ 

KET 

INSTR 

viAssertlntrSignal 












viAssertTrigger 



• 

• 

• 

• 


• 

• 

• 

• 

viAssertUtilSignal 












viBufRead 



• 

• 

• 

• 


• 

• 

• 

• 

viBufWrite 



• 

• 

• 

• 


• 

• 

• 

• 


viClear 



• 


• 

• 


• 

• 

• 

• 

viClose 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

viDisableEvent 


• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

viDiscardEvents 


• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

viEnableEvent 


• 

• 

• 

• 

• 

• 

• 

• 

• 

• 


viEventHandler 



• 


• 

• 


• 

• 

• 

• 

viFindNext 

• 


• 


• 

• 


• 

• 

• 

• 

viFindRsrc 


• 

• 


• 

• 


• 

• 

• 

• 

viFlush 



• 


• 

• 


• 

• 

• 

• 

viGetAttribute 

• 

• 

• 


• 

• 


• 

• 

• 

• 
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Interface 

— 

— 

GPIB 

GPIB- 

VXI 

VXI 

TCPIP 

ASRL 

Resource Class 

Find 

List 

Rsrc- 

Mgr 

INSTR 

INTFC 

INSTR 

INSTR 

MEM- 

ACC 

BACK¬ 

PLANE 

INSTR 

SOC¬ 

KET 

INSTR 

viMoveOutl6 





• 

• 

• 





viMoveOut32 





• 

• 

• 





viOpen 


• 

• 


• 

• 


• 

• 

• 

• 

viOpenDefaultRM 


• 

• 


• 

• 


• 

• 

• 

• 

viOut8 





• 

• 

• 






viOutl6 





• 

• 

• 





viOut32 





• 

• 

• 





viParseRsrc 


• 

• 


• 

• 


• 

• 

• 

• 

viPeek8 





• 

• 

• 





viPeek16 





• 

• 

• 






viPeek32 





• 

• 

• 





viPoke8 





• 

• 

• 





viPoke16 





• 

• 

• 





viPoke32 





• 

• 

• 





viPrintf 



• 

• 

• 




• 

• 

• 


viQueryf 



• 


• 

• 



• 


• 

viRead 



• 

• 

• 

• 



• 

• 

• 

viReadAsync 3 



• 

• 

• 

• 



• 

• 

• 

viReadSTB 



• 


• 

• 



• 

• 

• 

viReadToFile 



• 

• 

• 

• 



• 

• 

• 


a = implemented synchronously 


Chapter 7 


151 






















































































VISA Language Reference 

VISA Functions Overview 


Interface 

— 

— 

GPIB 

GPIB- 

VXI 

VXI 

TCPIP 

ASRL 

Resource Class 

Find 

List 

Rsrc- 

Mgr 

INSTR 

INTFC 

INSTR 

INSTR 

MEM- 

ACC 

BACK¬ 

PLANE 

INSTR 

SOC¬ 

KET 

INSTR 

viScanf 



• 

• 

• 

• 



• 

• 

• 

viSetAttribute 

• 

• 

• 


• 

• 


• 

• 

• 

• 

viSetBuf 



• 

• 

• 

• 



• 

• 

• 

viSPrintf 



• 

• 

• 

• 



• 

• 

• 

viSScanf 



• 

• 

• 

• 



• 

• 

• 


viStatusDesc 

• 

• 

• 


• 

• 


• 

• 

• 

• 

viTerminate 












viUninstallHandler 


• 

• 


• 

• 


• 

• 

• 

• 

viUnlock 



• 


• 

• 


• 

• 

• 

• 

viUnmapAddres s 





• 

• 

• 






viUnmapTrigger 





• 

• 

• 





viVPrintf 



• 

• 

• 

• 



• 

• 

• 

viVQueryf 



• 


• 

• 



• 


• 

viVScanf 



• 

• 

• 

• 



• 

• 

• 

viVSPrintf 



• 

• 

• 

• 



• 

• 

• 


viVSScanf 



• 

• 

• 

• 



• 

• 

• 

viVxiCommandQuery 






• 






viWaitOnEvent 


• 

• 


• 

• 


• 

• 

• 

• 

viWrite 



• 

• 

• 

• 



• 

• 

• 

viWriteAsync 



• 

• 

• 

• 



• 

• 

• 

viWriteFromFile 



• 

• 

• 

• 



• 

• 

• 


152 


Chapter 7 






















































































VISA Language Reference 

VISA Functions Overview 


VISA Functions by Type 

This table show VISA functions implemented by Agilent VISA grouped by 
type. The data types for the VISA function parameters (for example, 
ViSession, etc.) are defined in the VISA declarations file (see 
Appendix A - VISA Library Information). 


Operation 

Function (Type Parameterl , Type Parameter, ...); 

Opening/Closing Sessions 

Open Default RM Session 

viOpenDefaultRM(ViSession sesn) ; 

Open Session 

viOpen(ViSession sesn , ViRsrc rsrcName , ViAccessMode 
accessMode, ViUInt32 timeout, ViSession vi) ; 

Close Session 

viClose (ViSession/ViEvent/ViFindList vi) ; 

Control 

Get Attribute 

viGetAttribute(ViSession/ViEvent/ViFindList vi, 

ViAttr attribute, ViAttrState attrState) ; 

Set Attribute 

viSetAttribute(ViSession/ViEvent/ViFindList vi, 

ViAttr attribute, ViAttrState attrState) ; 

Get Status Code Description 

viStatusDesc(ViSession/ViEvent/ViFindList vi, 

ViStatus status, ViString desc) ; 

Terminate Asynchronous 

Operation 

viTerminate(ViSession vi, ViUIntl6 degree, 

ViJobld jobld) ; 

Lock Resource 

viLock(ViSession vi , ViAccessMode lockType , ViUInt32 
timeout, viKeyid requestedKey , viKeyid accessKey) ; 

Unlock Resource 

viUnlock (ViSession vi) ; 

Map Trigger Source Line to 
Destination Line 

viMapTrigger (ViSession vi, Vilntl6 trigSrc, Vilntl6 
trigDest, ViUIntl6 mode) ; 

Map Trigger Line to Another 
Trigger Line 

viUnmapTrigger (ViSession vi, Vilntl6 trigSrc, Vilntl6 
trigDest) ; 
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Operation 

Function (Type Parameterl , Type Parameter, ...); 

Event Handling/Interrupts 

Enable Event 

viEnableEvent(ViSession vi , ViEventType eventType, 
ViUIntl6 mechanism , ViEventFilter context) ; 

Disable Event 

viDisableEvent(ViSession vi , ViEventType eventType, 
viuintl6 mechanism) ; 

Discard Events 

viDiscardEvents(ViSession vi, ViEventType 
e vent Type, viuintl 6 mechanism) ; 

Wait on Event 

viWaitOnEvent(ViSession vi , ViEventType 
inEventType , ViUInt32 timeout, ViEventType 
outEventType , viEvent outContext) ; 

Install Handler 

vilnstallHandler(ViSession vi , ViEventType eventType, 
viHndlr handler, viAddr userHandle) ; 

Uninstall Handler 

viUninstallHandler(ViSession vi , ViEventType 
eventType, ViHndlr handler, ViAddr userHandle) ; 

Event Handler Prototype 

viEventHandler(ViSession vi , ViEventType eventType, 
ViEvent context, ViAddr userHandle) ; 

VXI Specific Series 

Send Device a Command/Query 
and/or Retrieve a Response 

viVxiCommandQuery(ViSession vi , ViUIntl6 mode, 
viuint32 cmd , viuint32 response) ; 

Searching 

Find Device 

viFindRsrc(ViSession sesn , ViString expr , ViFindList 
findList, viuint32 retcnt, viRsrc instrDesc) ; 

Find Next Device 

viFindNext(ViFindList findList, ViRsrc instrDesc); 

Parse Resource String to Get 
Interface Information 

viParseRsrc (ViSession sesn , ViRsrc rsrcName , VIUIntl6 
intfType, viuint!6 intfNum) ; 

Basic I/O 

Read Data from Device 

viRead(ViSession vi , ViBuf buf, ViUInt32 count, 
ViUInt32 retcount) ; 

Write Data to Device 

viWrite (ViSession vi , ViBuf buf, ViUInt32 count, 
ViUInt32 retcount) ; 

Read Data Asynchronously from 
Device 

viReadAsync(ViSession vi , ViBuf buf, ViUInt32 
count, viJobid jobld) ; 

Write Data Asynchronously to 
Device 

viWriteAsync (ViSession vi , ViBuf buf, ViUInt32 count, 
ViJobid jobld) ; 
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Operation 

Function (Type Parameterl , Type Parameter, ...); 

Basic I/O (continued) 

Clear a Device 

viClear (ViSession vi) ; 

Read Data Synchronously and 
Store Data in File 

viReadToFile (ViSession 1/7, ViConstString fileName, 
ViUInt32 count, ViUInt32 retCount) ; 

Write Data from File 

Synchronously 

viWriteFromFile (ViSession vi, ViConstString fileName, 
ViUInt32 count, ViUInt32 retCount) ; 

Assert Software/Hardware Trig 

viAssertTrigger (ViSession vi, ViUIntl6 protocol); 

Read Status Byte 

viReadSTB (ViSession vi , ViUIntl6 status); 

Formatted I/O 

Set Size of Buffer 

viSetBuf (ViSession vi , ViUIntl6 mask, ViUInt32 size); 

Unformatted Read to Formatted 

I/O Buffers 

viBufRead (ViSession vi, ViBuf buf ViUInt32 count, 

ViUInt32 retCount) ; 

Unformatted Write to Formatted 

I/O Buffers 

viBufWrite (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retCount); 

Flush Read and Write Buffers 

viFlush (ViSession vi, ViUIntl6 mask); 

Convert, Format, and Send 
Parameters to a Device 

viPrintf (ViSession 1/7, ViString writeFmt, argl,arg2, ...); 

Convert, Format, and Send 
Parameters to a Device 

viVPrintf (ViSession vi , ViString writeFmt , ViVAList 
pa rams) ; 

Write Data to a Buffer 

viSPrintf (ViSession vi, ViBuf buf, ViString writeFmt, argl, 
arg2, ...); 

Convert, Format, and Send 
Parameters to a Buffer 

viVSPrintf (ViSession vi, ViBuf buf, ViString writeFmt, 
ViVAList params) ,- 

Receive Data from Device, 

Format and Store Data 

viScanf (ViSession vi , ViString readFmt, argl, arg2, ...); 

Receive Data from Device, 

Format and Store Data 

viVScanf (ViSession 1/7, ViString readFmt, ViVAList 
params) ; 

Receive Data from Buffer, Format 
and Store Data 

viSScanf (ViSession vi, ViBuf buf, ViString readFmt, argl, 
arg2, ...); 

Receive Data from Buffer, Format 
and Store Data 

viVSScanf (ViSession vi, ViBuf buf, ViString readFmt, 
ViVAList params ); 
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Operation 

Function (Type Parameterl , Type Parameter ,...); 

Formatted I/O (continued) 

Formatted Write and Read 
Operation 

viQueryf (ViSession vi, ViString writeFmt, ViString 
readFmt, argl, arg2, . . .) ; 

Formatted Write and Read 
Operation 

viVQueryf (ViSession vi, ViString writeFmt, ViString 
readFmt, viVAList params) ; 

Memory I/O 

Read 8-bit Value from Memory 
Space 

viln8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUInt8 val8) ; 

Read 16-bit Value from Memory 
Space 

vilnl6(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUIntl6 val16) ; 

Read 32-bit Value from Memory 
Space 

viln32(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUInt32 va/32) ; 

Write 8-bit Value to Memory 

Space 

viOut8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUInt8 val8) ; 

Write 16-bit Value to Memory 
Space 

viOutl6(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUIntl6 vail6) ; 

Write 32-bit Value to Memory 
Space 

viOut32(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViUInt32 va/32) ; 

Move data from source to 
destination 

viMove (ViSession vi, ViUIntl6 srsSpace, ViBusAddress 
srcOffset, Viuintl6 srcWidth, Viuintl6 destSpace, 
ViBusAddress destOffset, ViUIntl6 destWidth, 
viBusSize length) 

Move data from source to 
destination asynchronously 

viMoveAsync (ViSession vi, ViUIntl6 srsSpace, 

ViBusAddress srcOffset, ViUIntl6 srcWidth, ViUIntl6 
destSpace, ViBusAddress destOffset, ViUIntl6 
destWidth, ViBusSize length, viJobid jobld) 

Move 8-bit Value from Device 
Memory to Local Memory 

viMoveIn8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset ,ViBusSize length, ViAUInt8 buf8) ; 

Move 16-bit Value from Device 
Memory to Local Memory 

viMovelnl6(ViSession vi, ViUIntl6 space, ViBusAddress 
offset ,ViBusSize length, ViAUIntl6 buf16) ; 

Move 32-bit Value from Device 
Memory to Local Memory 

viMoveIn32(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViBusSize length, ViAUInt32 buf32) ; 

Move 8-bit Value from Local 
Memory to Device Memory 

viMoveOut8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViBusSize length, ViAUInt8 buf8) ; 


156 


Chapter 7 























VISA Language Reference 

VISA Functions Overview 


Operation 

Function (Type Parameterl , Type Parameter2, ...); 

Memory I/O (continued) 

Move 16-bit Value from Local 
Memory to Device Memory 

viMoveOutl6(ViSession vi , ViUIntl6 space, 

ViBusAddress offset, ViBusSize length, 

ViAUIntl6 buf16) ; 

Move 32-bit Value from Local 
Memory to Device Memory 

viMoveOut32(ViSession vi , ViUIntl6 space, 

ViBusAddress offset, ViBusSize length, 

ViAUInt32 buf32) ; 

Map Memory Space 

viMapAddress(ViSession vi , ViUIntl6 mapSpace, 
ViBusAddress mapBase , ViBusSize mapSize, 
viBoolean access, viAddr suggested , viAddr address); 

Unmap Memory Space 

viUnmapAddress (ViSession vi) ; 

Read 8-bit Value from Address 

viPeek8 (ViSession vi , ViAddr addr , ViUInt8 val8) ; 

Read 16-bit Value from Address 

viPeekl6(ViSession vi, ViAddr addr, ViUIntl6 val16); 

Read 32-bit Value from Address 

viPeek32 (ViSession vi, ViAddr addr, ViUInt32 val32) ; 

Write 8-bit Value to Address 

viPoke8 (ViSession vi , ViAddr addr , ViUInt8 val8) ; 

Write 16-bit Value to Address 

viPokel6 (ViSession vi, ViAddr addr, ViUIntl6 val16) ; 

Write 32-bit Value to Address 

viPoke32 (ViSession vi, ViAddr addr, ViUInt32 val32) ; 

GPIB Specific Services 

Control GPIB REN Interface Line 

viGpibControlREN (ViSession vi, ViUIntl6 mode) ; 

Control GPIB ATN Interface Line 

viGpibControlATN (ViSession vi, ViUIntl6 mode); 

Write GPIB Command Bytes 
on the bus 

viGpibCommand (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retcount ) ; 

Tell GPIB Device to Become 
Controller in Charge (CIC) 

viGpibPassControl (ViSession vi, ViUIntl6 primAddr, 
viuintl6 secAddr) ; 

Pulse Interface Clear (IFC) Line 

viGpibSendIFC (ViSession vi) ; 
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Description 

Parameters 
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viAssertlntrSignal 


viAssertlntrSignal 

viAssertlntrSignal (ViSession vi, Vilntl6 mode, 
ViUInt32 statusID) ; 


Asserts the specified device interrupt or signal. This operation can be used 
to assert a device interrupt condition. In VXI, for example, this can be done 
with either a VXI signal or a VXI interrupt. On certain bus types, the 
statusID parameter may be ignored. 


NOTE 

This function is not implemented in Agilent VISA. 


Name 

Direction 

Type 

Description 

mode 

IN 

Vilntl6 

This specifies how to assert the 
interrupt. See the Description section 
for actual values. 

statusID 

IN 

ViUInte32 

This is the status value to be presented 
during an interrupt acknowledge cycle. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Values for mode Parameter 


mode 

Action Description 

VI ASSERT IRQ1 - 
VI ASSERT IRQ7 

Send the interrupt via the specified VXI/VME IRQ line. 
This uses the standard VXI/VME ROAK (release on 
acknowledge) interrupt mechanism rather than the 
older VME RORA (release on register access) 
mechanism. 

VI ASSERT SIGNAL 

Send the notification via a VXI signal. 

VI ASSERT USE 

ASSIGNED 

Use whatever notification method that has been 
assigned to the local device. 
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Return Values 


See Also 
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viAssertlntrSignal 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INTR PENDING 

An interrupt is still pending from a previous 
call. 

VI ERROR INV MODE 

The value specified by the mode parameter is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP INTR 

The interface cannot generate an interrupt on 
the requested level or with the requested 
statusID value. 

VI ERROR NSUP MODE 

The specified mode is not supported by this 
VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


BACKPLANE Resource Description 
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Description 


Parameters 
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viAssertTrigger 


viAssertTrigger 

viAssertTrigger (ViSession vi, ViUIntl6 protocol); 


NOTE 

This function is not supported with the GPIB-VXI interface. 


Assert software or hardware trigger. This operation will source a software or 
hardware trigger dependent on the interface type. For a GPIB device, the 
device is addressed to listen and then the GPIB GET command is sent. 

For a VXI device, if vi_attr_trig_id is vi_trig_sw, the device is sent 
the Word Serial Trigger command. For any other values of the attribute, a 
hardware trigger is sent on the line corresponding to the value of that 
attribute. For a GPIB device, if vi_attr_trig_id is vi_trig_sw, the 
device is addressed to Listen and a Group Execute Trigger (GET) is sent. 

For a serial session to a Serial device or TCPIP socket, if 
vi_attr_io_prot is vi_prot_4882_strs, the device is sent the 
string "*TRG\n". Otherwise, this operation is not valid. 

In the Parameters table, the protocol values are: 

■ VI_TRIG_PROT_DEFAULT is VI_TRIG_PROT_SYNC for VXI 

■ vi_trig_prot_on asserts the trigger 

■ vi_trig_prot_off deasserts the trigger 

■ vi_trig_prot_sync pulses the trigger (assert followed by 
deassert) 


Name 

Direction 

Type 

Description 

protocol 

IN 

ViUIntl6 

Trigger protocol to use during assertion. 
Valid values are: 

VI TRIG PROT DEFAULT, 

VI TRIG PROT ON, 

vi trig prot off, and 

VI TRIG PROT SYNC. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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viAssertTrigger 


Return Values 


Type vistatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

The specified trigger was successfully 
asserted to the device. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session 
has been lost. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error 
occurred during transfer. 

VI ERROR INV PROT 

The protocol specified is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup 
is invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR LINE IN USE 

The specified trigger line is currently in 

use. 

VI ERROR NCIC 

The interface associated with the given vi 
is not currently the controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both 
NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this 
function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred 
during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred 
during transfer. 
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See Also 


Error Codes 

Description 

VI ERROR RSRC LOCKED 

Specified operation could not be 
performed because the resource 
identified by vi has been locked for this 
kind of access. 

VI ERROR TMO 

Timeout expired before function 
completed. 


vi_attr_trig_id attribute. Set this attribute to the trigger mechanism/ 
trigger line to use. vi_event_trigger description for details on trigger 
specifiers. 


162 


Chapter 7 







VISA Language Reference 

viAssertlltilSignai 


Syntax 

Description 


Parameters 


Return Values 


viAssertlltilSignai 

viAssertUtilSignal (ViSession vi, ViUIntl6 line) ; 


Asserts the specified utility bus signal. This operation can be used to assert 
either the SYSFAIL or SYSRESET utility bus interrupts on the VXIbus 
backplane. This operation is valid only on VXI Mainframe Backplane 
(BACKPLANE) and on Servant Device-Side (SERVANT) resource sessions. 


NOTE 

This function is not supported in Agilent VISA. 

Asserting SYSRESET (also known as HARD RESET in the VXI 
specification) should be used only when it is necessary to promptly 
terminate operation of all devices in a VXIbus system. This is a serious 
action that always affects the entire VXIbus system. 


Name 

Direction 

Type 

Description 

line 

IN 

ViUIntl6 

Specifies the utility bus signal to assert. 
This can be the value 

VI UTIL ASSERT SYSRESET, 

VI UTIL ASSERT SYSFAIL, Or 

VI UTIL DEASSERT SYSFAIL 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 
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viAssertUtilSignal 


See Also 


Error Codes 

Description 

VI ERROR INV LINE 

The value specified by the line parameter is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before operation completed. 


BACKPLANE Resource Description 
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viBufRead 


Syntax 

Description 

Parameters 


Return Values 


viBufRead 

viBufRead (ViSession vi, ViBuf buf, ViUInt32 count, 
viuint32 retCount) ; 


Similar to viRead, except that the operation uses the formatted I/O read 
buffer for holding data read from the device. This operation is similar to 
viRead and does not perform any kind of data formatting. It differs from 
viRead in that the data is read from the formatted I/O read buffer (the same 
buffer as used by viScanf and related operations) rather than directly from 
the device. This operation can intermix with the viScanf operation, but use 
with the viRead operation is discouraged. 


Name 

Direction 

Type 

Description 

buf 

OUT 

ViBuf 

Represents the location of a buffer 
to receive data from the device. 

count 

IN 

ViUInt32 

Number of bytes to be read. 

retCount 

OUT 

ViUInt32 

Represents the location of an integer 
that will be set to the number of bytes 
actually transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Value for retCount Parameter 


Value 

Action Description 

VI NULL 

Do not return the number of bytes transferred. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 
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viBufRead 


See Also 


Completion Codes 

Description 

VI_SUCCESS 

The operation completed successfully and 
the END indicator was received (for 
interfaces that have END indicators). 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 

VI SUCCESS TERM CHAR 

The specified termination character was read. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR 10 

An unknown I/O error occurred during 
transfer. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


viWrite, viScanf 
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viBufWrite 


Syntax 

Description 


Parameters 


viBufWrite 

viBufWrite (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retCount) ; 


Similar to viWrite, except the data is written to the formatted I/O write 
buffer rather than directly to the device. This operation is similar to viWrite 
and does not perform any kind of data formatting. 

It differs from viWrite in that the data is written to the formatted I/O write 
buffer (the same buffer as used by viPrintf and related operations) rather 
than directly to the device. This operation can intermix with the viPrintf 
operation, but mixing it with the viWrite operation is discouraged. 

If you pass vi_null as the retCount parameter to the viBufWrite 
operation, the number of bytes transferred will not be returned. This may be 
useful if it is important to know only whether the operation succeeded or 
failed. 


Name 

Direction 

Type 

Description 

buf 

IN 

ViBuf 

Represents the location of a data block 
to be sent to the device. 

count 

IN 

ViUInt32 

Number of bytes to be written. 

retCount 

OUT 

ViUInt32 

Represents the location of an integer 
that will be set to the number of bytes 
actually transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Value for retCount Parameter 


Value 

Action Description 

VI NULL 

Do not return the number of bytes transferred. 
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Return Values 


See Also 


VISA Language Reference 

viBufWrite 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start write operation because 
setup is invalid (due to attributes being set 
to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during 
transfer. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


viWrite, viBufRead 
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viClear 


Syntax 

Description 

Parameters 

Return Values 


viClear 

viClear (ViSession vi) ; 

Clear a device. This operation performs an IEEE 488.1-style clear of the 
device. For VXI, the Word Serial Clear command should be used. For GPIB 
systems, the Selected Device Clear command should be used. For a 
session to a Serial device or TCPIP socket, if vi_attr_io_prot is 
vi_prot_ 4882_s trs , the device is sent the string "*CLS\n". Otherwise, 
this operation is not valid. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has 
been lost. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR NCIC 

The interface associated with the given vi is 
not currently the controller in charge. 
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viClear 


Error Codes 

Description 

VI ERROR NLISTENERS 

No Listeners condition is detected (both 

NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred 
during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred 
during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 
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viClose 


Syntax 

Description 


Parameters 

Return Values 


viClose 

viClose (ViSession/ViEvent/ViFindList vi) ; 


This function closes the specified resource manager session, device 
session, find list (returned from the viFindRsrc function), or event context 
(returned from the viWaitOnEvent function, or passed to an event 
handler). In this process, all the data structures that had been allocated for 
the specified vi are freed. 


NOTE 

The viClose function should not be called from within an event handler. 
In VISA 1.1 and greater, viClose (VI_NULL) returns 
VI WARN NULL object rather than an error. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

ViEvent 

ViFindList 

Unique logical identifier to a session, event, 
or find list. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Session closed successfully. 

VI WARN NULL OBJECT 

The specified object reference is uninitialized. 
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viClose 


See Also 


Error Codes 

Description 

VI ERROR CLOSING FAILED 

Unable to deallocate the previously allocated 
data structures corresponding to this session or 
object reference. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 


viOpen, viFindRsrc, viWaitOnEvent, viEventHandler 
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viDisableEvent 


Syntax 

Description 


Parameters 


viDisableEvent 

viDisableEvent (ViSession vi, ViEventType eventType, 
ViUIntl6 mechanism) ; 


This function disables servicing of an event identified by the eventType 
parameter for the mechanisms specified in the mechanism parameter. 
Specifying vi_all_enabled_events for the eventType parameter 
allows a session to stop receiving all events. 

The session can stop receiving queued events by specifying vi_queue. 
Applications can stop receiving callback events by specifying either 
VI_HNDLR or VI_SUSPEND_HNDLR. Specifying VI_ALL_MECH disables 
both the queuing and callback mechanisms. 

viDisableEvent prevents new event occurrences from being added to 
the queue(s). However, event occurrences already existing in the queue(s) 
are not discarded. 


Name 

Direction 

Type 

Description 

eventType 

IN 

ViEventType 

Logical event identifier. (See the 
following tables.) 

mechanism 

IN 

ViUIntl6 

Specifies event handling 
mechanisms to be disabled. 

The queuing mechanism is 
disabled by specifying 

VI QUEUE. 




The callback mechanism is 
disabled by specifying vi hndlr 
or VI SUSPEND HNDLR. It is 
possible to disable both 
mechanisms simultaneously 
by specifying vi all mech. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 
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viDisableEvent 


Special Value for eventType Parameter 


Value 

Action Description 

VI ALL ENABLED EVENTS 

Disable all events that were previously enabled. 


The following events can be disabled: 


Event Name 

Description 

VI EVENT 10 COMPLETION 

Notification that an asynchronous operation has 
completed. 

VI EVENT SERVICE REQ 

Notification that a device is requesting service. 

VI EVENT TRIG 

Notification that a hardware trigger was received 
from a device. 

VI EVENT VXI SIGP 

Notification that a VXI signal or VXI interrupt has 
been received from a device. 


Special Values for mechanism Parameter 


Value 

Action Description 

VI ALL MECH 

Disable this session from receiving the specified 
event(s) via any mechanism. 

VI HNDLROr 

VI SUSPEND HNDLR 

Disable this session from receiving the specified 
event(s) via a callback handler or a callback 
queue. 

VI QUEUE 

Disable this session from receiving the specified 
event(s) via the waiting queue. 


Return Values 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Event disabled successfully. 

VI SUCCESS EVENT DIS 

Specified event is already disabled for at least 
one of the specified mechanisms. 
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VISA Language Reference 

viDisableEvent 


See Also 


Error Codes 

Description 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 


See the handler prototype viEventHandler for its parameter 
description, and viEnableEvent. Also, see vilnstallHandler and 
viUninstallHandler descriptions for information about installing and 
uninstalling event handlers. See event descriptions for context structure 
definitions. 
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Syntax 

Description 

Parameters 


VISA Language Reference 

viDiscardEvents 


viDiscardEvents 

viDiscardEvents (ViSession 1/7, ViEventType eventType, 
ViUIntl6 mechanism) ; 


This function discards all pending occurrences of the specified event types 
for the mechanisms specified in a given session. The information about all 
the event occurrences which have not yet been handled is discarded. This 
function is useful to remove event occurrences that an application no longer 
needs. 

The event occurrences discarded by applications are not available to a 
session at a later time. This operation causes loss of event occurrences. 
The viDiscardEvents operation does not apply to event contexts that 
have already been delivered to the application. 


Name 

Direction 

Type 

Description 

eventType 

IN 

ViEventType 

Logical event identifier. (See the 
following tables.) 

mechanism 

IN 

ViUIntl6 

Specifies the mechanisms for which 
the events are to be discarded, 
vi queue is specified for the 
queuing mechanism and 
vi suspend hndlr is specified 
for the pending events in the 
callback mechanism. It is possible 
to specify both mechanisms 
simultaneously by specifying 

VI ALL MECH. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 
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viDiscardEvents 


Special Value for eventType Parameter 


Value 

Action Description 

VI ALL ENABLED EVENTS 

Discard events of every type that is enabled. 


The following events can be discarded: 


Event Name 

Description 

VI EVENT 10 COMPLETION 

Notification that an asynchronous operation has 
completed. 

VI EVENT SERVICE REQ 

Notification that a device is requesting service. 

VI EVENT TRIG 

Notification that a hardware trigger was received 
from a device. 

VI EVENT VXI SIGP 

Notification that a VXI signal or VXI interrupt has 
been received from a device. 


Special Values for mechanism Parameter 


Value 

Action Description 

VI ALL MECH 

Discard the specified event(s) from all 
mechanisms. 

VI QUEUE 

Discard the specified event(s) from the waiting 
queue. 

VI SUSPEND HNDLR 

Discard the specified event(s) from the callback 
queue. 
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viDiscardEvents 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Event queue flushed successfully. 

VI SUCCESS QUEUE EMPTY 

Operation completed successfully, but queue 
was empty. 


Error Codes 

Description 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 


See Also viEnableEvent, viWaitOnEvent, vilnstallHandler 
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viEnableEvent 


Syntax 

Description 


viEnableEvent 

viEnableEvent (ViSession vi, ViEventType eventType, 
ViUIntl6 mechanism, ViEventFilter context); 


This function enables notification of an event identified by the eventType 
parameter for mechanisms specified in the mechanism parameter. The 
specified session can be enabled to queue events by specifying vi_queue. 


NOTE 

VISA cannot callback to a Visual Basic function. Thus, you can only use 
the VI_QUEUE mechanism in viEnableEvent. There is no way to install 
a VISA event handler in Visual Basic. 


Applications can enable the session to invoke a callback function to execute 
the handler by specifying vi_hndlr. The applications are required to install 
at least one handler to be enabled for this mode. 

Specifying vi_suspend_hndlr enables the session to receive callbacks, 
but the invocation of the handler is deferred to a later time. Successive calls 
to this function replace the old callback mechanism with the new callback 
mechanism. 

Specifying vi_all_enabled_events for the eventType parameter refers 
to all events which have previously been enabled on this session, making it 
easier to switch between the two callback mechanisms for multiple events. 

Event queuing and callback mechanisms operate completely independently. 
As such, enabling and disabling of the two modes in done independently 
(enabling one of the modes does not enable or disable the other mode). 

For example, if viEnableEvent is called once with VI_HNDLR and called 
a second time with vi_queue, both modes would be enabled. 

If viEnableEvent is called with the mechanism parameter equal to the 
"bit-wise OR" Of VI_SUSPEND_HNDLR and VI_HNDLR, viEnableEvent 
returns vi error inv mech. 
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viEnableEvent 


If the event handling mode is switched from vi_suspend_hndlr to 
vi_hndlr for an event type, handlers that are installed for the event are 
called once for each occurrence of the corresponding event pending in the 
session (and dequeued from the suspend handler queue) before switching 
the modes. 

A session enabled to receive events can start receiving events before the 
viEnableEvent operation returns. In this case, the handlers set for an 
event type are executed before the completion of the enable operation. 

If the event handling mode is switched from vi_hndlr to 
vi_suspend_hndlr for an event type, handler invocation for occurrences 
of the event type is deferred to a later time. If no handler is installed for an 
event type, the request to enable the callback mechanism for the event type 
returns vi_error_hndlr_ninstalled. 

If a session has events pending in its queue(s) and viciose is invoked on 
that session, all pending event occurrences and the associated event 
contexts that have not yet been delivered to the application for that session 
are freed by the system. 


Parameters 


Name 

Direction 

Type 

Description 

context 

IN 

ViEventFilter 

vi null (Not used for VISA 1.0.) 

eventType 

IN 

ViEventType 

Logical event identifier. 

mechanism 

IN 

ViUIntl6 

Specifies event handling 
mechanisms to be enabled. The 
queuing mechanism is enabled by 
vi queue, and the callback 
mechanism is enabled by 

VI HNDLROr 

VI SUSPEND HNDLR. 




It is possible to enable both 
mechanisms simultaneously by 
specifying "bit-wise OR" of 
vi queue and one of the two mode 
values for the callback mechanism. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 
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viEnableEvent 


Special Value for eventType Parameter 


Value 

Action Description 

VI ALL ENABLED EVENTS 

Switch all events that were previously enabled to 
the callback mechanism specified in the 
mechanism parameter. 


The following events can be enabled: 


Event Name 

Description 

VI EVENT 10 COMPLETION 

Notification that an asynchronous operation has 
completed. 

VI EVENT SERVICE REQ 

Notification that a device is requesting service. 

VI EVENT TRIG 

Notification that a hardware trigger was received 
from a device. 

VI EVENT VXI SIGP 

Notification that a VXI signal or VXI interrupt has 
been received from a device. 


Special Values for mechanism Parameter 


Value 

Action Description 

VI HNDLR 

Enable this session to receive the specified event via 
a callback handler, which must have already been 
installed via vilnstallHandler. 

VI QUEUE 

Enable this session to receive the specified event via 
the waiting queue. Events must be retrieved manually 
via the viWaitOnEvent function. 

VI SUSPEND HNDLR 

Enable this session to receive the specified event via 
a callback queue. Events will not be delivered to the 
session until viEnableEvent is invoked again with 
the vi hndlr mechanism. 


NOTE 

Any combination of VISA-defined values for different parameters 
of this function is also supported (except for vi_hndlr and 
vi_ s uspend_hndlr, which apply to different modes of the same 
mechanism). 
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Return Values 


See Also 


VISA Language Reference 

viEnableEvent 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Event enabled successfully. 

VI SUCCESS EVENT EN 

Specified event is already enabled for at 
least one of the specified mechanisms. 


Error Codes 

Description 

VI ERROR HNDLR NINSTALLED 

A handler is not currently installed for the 
specified event. The session cannot be 
enabled for the vi hndlr mode of the 
callback mechanism. 

VI ERROR INV CONTEXT 

Specified event context is invalid. 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP MECH 

The specified mechanism is not supported 
for the given event type. 


See the handler prototype viEventHandler for its parameter description 
and viDisableEvent. Also, see the vilnstallHandler and 
viUninstallHandler descriptions for information about installing and 
uninstalling event handlers. 
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viEventHandler 


Syntax 

Description 


viEventHandler 

viEventHandler(ViSession vi , ViEventType eventType, 
ViEvent context, ViAddr userHandle) ; 


This is a prototype for a function, which you define. The function you define 
is called whenever a session receives an event and is enabled for handling 
events in the vi_hndlr mode. The handler services the event and returns 
vi_success on completion. VISA event handlers must be declared as 
follows. 

ViStatus _VI_FUNCH MyEventHandler(ViSession vi, 
ViEventType eventType, ViEvent context, 

ViAddr userHandle) ; 

The _vi_funch declaration is required to make sure the handler is of the 
proper type. If _vi_funch is not included, stack corruption may occur on 
the function call or return. The _vi_funch declaration is very important 
since it declares the function of type stdcall which VISA requires. Visual 
Studio C++ defaults to cdecl which will not work. When the handler returns, 
it will generate an access violation because the stack gets corrupted. 

Because each eventType defines its own context in terms of attributes, refer 
to the appropriate event definition to determine which attributes can be 
retrieved using the context parameter. 

Because the event context must still be valid after the user handler returns 
(so that VISA can free it up), an application should not invoke the viciose 
operation on an event context passed to a user handler. 

If the user handler will not return to VISA, the application should call 
viciose on the event context to manually delete the event object. This 
may occur when a handler throws a C++ exception in response to a VISA 
exception event. 

Normally, an application should return vi_success from all callback 
handlers. If a specific handler does not want other handlers to be invoked 
for the given event for the given session, it should return 
vi_success_nchain. No return value from a handler on one session 
will affect callbacks on other sessions. 
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viEventHandler 


NOTE 

Future versions of VISA (or specific implementations of VISA) may take 
actions based on other return values, so users should return 
vi_success from handlers unless there is a specific reason to do 
otherwise. 


This table lists events and associated read-only attributes implemented by 
Agilent VISA that can be read to get event information on a specific event. 
Use the viReadSTB function to read the status byte of the service request 

Instrument Control (INSTR) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT SERVICE 

REQUEST 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT SERVICE 

REQ 

VI EVENT VXI SIGP 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI STOP 


VI ATTR SIGP STATUS ID 

ViUIntl6 

OtoFFFFh 

VI EVENT TRIG 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIG 


VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 
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viEventHandler 


Memory Access (MEMACC) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 


GPIB Bus Interface (INTFC) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT GPIB CIC 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB CIC 


VI ATTR GPIB RECV CIC 

STATE 

ViBoolean 

VI TRUE 

VI FALSE 

VI EVENT GPIB TALK 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB TALK 

VI EVENT GPIB 

LISTEN 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB 

LISTEN 

VI EVENT CLEAR 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT CLEAR 

VI EVENT TRIGGER 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIGGER 


VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG SW 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 
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viEventHandler 


VXI Mainframe Backplane (BACKPLANE) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT TRIG 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

VI EVENT VXI VME 

SYSFAIL 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI VME 

SYSFAIL 

VI EVENT VXI VME 

SYSRESET 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI VME 

SYSRESET 


TCPIP Socket (SOCKET) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 


Parameters 


Name 

Direction 

Type 

Description 

context 

IN 

Vi Event 

A handle specifying the unique 
occurrence of an event. 

eventType 

IN 

ViEventType 

Logical event identifier. 

userHandte 

IN 

ViAddr 

A value specified by an application 
that can be used for identifying 
handlers uniquely in a session for 
an event. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


186 


Chapter 7 





























Return Values 


See Also 


VISA Language Reference 

viEventHandler 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Event enabled successfully. 


See Chapter 4 - Programming with VISA for more information on event 
handling and exception handling. 
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Syntax 

Description 

Parameters 


Return Values 


See Also 


VISA Language Reference 

viFindNext 


viFindNext 

viFindNext (ViFindList findList, ViPRsrc instrDesc) ; 

This function returns the next resource found in the list created by 
viFindRsrc. The list is referenced by the handle that was returned by 
viFindRsrc. 


Name 

Direction 

Type 

Description 

findList 

IN 

ViFindList 

Describes a find list. This parameter must 
be created by viFindRsrc. 

instrDesc 

OUT 

ViPRsrc 

Returns a string identifying location of a 
device. Strings can be passed to viOpen 
to establish a session to the device. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Resource(s) found. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP OPER 

Given findList does not support this function. 

VI ERROR RSRC NFOUND 

There are no more matches. 


viFindRsrc 


188 


Chapter 7 



















VISA Language Reference 

viFindRsrc 


Syntax 

Description 


viFindRsrc 


viFindRsrc(ViSession sesn , ViString expr, ViFindList 
findList, ViUlnt32 retcnt, ViRsrc instrDesc) ; 


This function queries a VISA system to locate the resources associated with 
a specified interface. This function matches the value specified in the expr 
parameter with the resources available for a particular interface. 

On successful completion, it returns the first resource found in the list and 
returns a count to indicate if there were more resources found that match 
the value specified in the expr parameter. 

This function also returns a handle to a find list. This handle points to the list 
of resources, and it must be used as an input to viFindNext. When this 
handle is no longer needed, it should be passed to viciose. 

The search criteria specified in the expr parameter has two parts: a regular 
expression over a resource string and an optional logical expression over 
attribute values. The regular expression is matched against the resource 
strings of resources known to the VISA Resource Manager. 

If the resource string matches the regular expression, the attribute values of 
the resource are then matched against the expression over attribute values. 
If the match is successful, the resource has met the search criteria and gets 
added to the list of resources found. (Agilent VISA does not support 
matching of attribute values.) 

The optional attribute expression allows construction of expressions with the 
use of logical ANDs, ORs and NOTs. Equal (==) and unequal (!=) 
comparators can be used compare attributes of any type. In addition, other 
inequality comparators (>, <, >=, <=) can be used to compare attributes of 
numeric type. Only global attributes can be used in the attribute expression. 

The syntax of expr is defined as follows. The grouping operator () in a 
logical expression has the highest precedence, The not operator ! in a 
logical expression has the next highest precedence after the grouping 
operator, and the or operator | | in a logical expression has the lowest 
precedence. (Agilent VISA does not support the use of logical expressions 
over all attribute values.) 
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viFindRsrc 


Special Character 

Meaning 

&& 

Logical AND 

1 1 

Logical OR 

1 

Logical negation (NOT) 

0 

Parentheses 


expr := 

regularExpr ['{' attrExpr '} 1 ] 

attrExpr := 

attrTerm | 

attrExpr 'll' attrTerm 

attrTerm := 

attrFactor | 

attrTerm '&&' attrFactor 
attrFactor := 

' (' attrExpr ') ' | 

'!' attrFactor 
relationExpr 
relationExpr := 

attributeld compareOp numValue I 
attributeld equalityOp stringValue 

compareOp := 

'==' | '!=' | '>' | '<' | '>=' | '<=' 
equalityOp := 

'==' | > 1 =' 

attributeld : = 

character (characteridigit|underscore)* 

numValue := 

digit! I 

'-' digit! I 

'Ox' hex_digit! 

'OX' hex_digit! 
stringValue := 

'"' character* '"' 
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VISA Language Reference 

viFindRsrc 


Some examples are: 


Expr 

Meaning 

GPIB[0-9]*::?*::?*::INS TR 

{VI_A TTR_GPIB_SEC ON DA RY_ADDR > 0} 

Find all GPIB devices that have secondary 
addresses greater than 0. 

ASRL?*INSTR{VI_A TTR_ASRL_BAUD == 9600} 

Find all serial ports configured at 9600 baud. 

?*VXI?*INSTR{VI ATTR MANF ID == 0xFF6 && 
!(VI_ATTR_VXI_LA == 0 || VI_ATTR_SLOT <= 0)} 

Find all VXI instrument resources whose 
manufacturer ID is FF6 and who are not logical 
address 0, slot 0, or external controllers. 


Local attributes are not allowed in the logical expression part of the expr 
parameter to the viFindRsrc operation. viFindRsrc uses a case- 
insensitive compare function when matching resource names against the 
regular expression specified in expr. 

If the value VI_NULL is specified in the findList parameter of viFindRsrc 
and the return value is successful, VISA automatically invokes viciose on 
the find list handle rather than returning it to the application. 

The findList and retCnt parameters to the viFindRsrc operation are 
optional. They can be used if only the first match is important and the 
number of matches is not needed. Calling viFindRsrc with 
"vxi?*instr" will return the same resources as invoking it with 
"vxi?*instr". 

All resource strings returned by viFindRsrc must be recognized by 
viParseRsrc and viOpen. However, not all resource strings that 
can be parsed or opened have to be findable. 
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VISA Language Reference 

viFindRsrc 


Parameters 


Name 

Direction 

Type 

Description 

expr 

IN 

ViString 

This expression sets the criteria to 
search an interface or all interfaces for 
existing devices. (See the following 
table for description string format.) 

findList 

OUT 

ViFindList 

Returns a handle identifying this 
search session. This handle will be 
used as an input in viFindNext. 

instrDesc 

OUT 

ViRsrc 

Returns a string identifying the 
location of a device. Strings can then 
be passed to viOpen to establish a 
session to the given device. 

retcnt 

OUT 

ViUInt32 

Number of matches. 

sesn 

IN 

ViSession 

Resource Manager session (should 
always be the Default Resource 
Manager for VISA returned from 
viOpenDefaultRM). 


Description String for expr Parameter 


Interface 

Expression 

GPIB 

GPIB[0-9]*::?*INSTR 

VXI 

VXI?*INSTR 

GPIB-VXI 

GPIB-VXI?*INSTR 

GPIB and GPIB-VXI 

GPIB?*INSTR 

All VXI 

?*VXI[0-9]*::?*INSTR 

ASRL 

ASRL[0-9]*::?*INSTR 

All 

?*INSTR 


Special Value for findList Parameter 


Value 

Action Description 

VI NULL 

Do not return a find list handle. 
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VISA Language Reference 

viFindRsrc 


Special Value for retcnt Parameter 


Value 

Action Description 

VI NULL 

Do not return the number of matches. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Resource(s) found. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP OPER 

The given sesn does not support this function. 

VI ERROR INV EXPR 

Invalid expression specified for search. 

VI ERROR RSRC NFOUND 

Specified expression does not match any devices. 


See Also viFindNext, viClose 
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Syntax 

Description 


VISA Language Reference 

viFlush 


viFlush 

viFlush (ViSession vi, ViUIntl6 mask); 


Manually flush the specified buffers associated with formatted I/O operations 
and/or serial communication. The values for the mask parameter are: 


Flag 

Interpretation 

VI 10 IN BUF 

Discard receive buffer contents (same as 

VI 10 IN BUF DISCARD). 

VI 10 IN BUF DISCARD 

Discard eceive buffer contents (does not perform 
an I/O to the device). 

VI 10 OUT BUF 

Flush the transmit buffer by writing all buffered 
data to the device. 

VI 10 OUT BUF DISCARD 

Discard transmit buffer contents (does not perform 
any I/O to the device). 

VI READ BUF 

Discard the read buffer contents and, if data was 
present in the read buffer and no END-indicator was 
present, read from the device until encountering an 
END indicator (which causes the loss of data). 

This action resynchronizes the next viScanf call 
to read a TERMINATED RESPONSE MESSAGED 
(See the IEEE 488.2 standard.) 

VI READ BUF DISCARD 

Discard read buffer contents (does not perform any 
I/O to the device). 

VI WRITE BUF 

Flush the write buffer by writing all buffered data 
to the device. 

VI WRITE BUF DISCARD 

Discard write buffer contents (does not perform any 
I/O to the device). 


It is possible to combine any of these read flags and write flags for different 
buffers by ORing the flags. However, combining two flags for the same 
buffer in the same call to viFlush is illegal. When using formatted I/O 
operations with a serial device, a flush of the formatted I/O buffers also 
causes the corresponding serial communication buffers to be flushed. 

For example, calling viFlush with vi_write_buf also flushes the 
VI IO OUT BUF. 
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VISA Language Reference 

viFlush 


For backward compatibility, vi_io_in_buf is the same as 
VI_ASRL_IN_BUF, vi_io_in_buf_discard is the same as 
vi_asrl_in_buf_dIscard, vi_io_out_buf is the same as 
vi_asrl_out_buf, and vi_io_out_buf_d i scard is the same as 

VI ASRL OUT BUF DISCARD. 


Parameters 


Name 

Direction 

Type 

Description 

mask 

IN 

ViUIntl6 

Specifies the action to be taken with flushing 
the buffer. (See the following table.) 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Buffers flushed successfully. 


Error Codes 

Description 

VI ERROR INV MASK 

The specified mask does not specify a valid flush 
function on read/write resource. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform read/write function because 
of I/O error. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

The read/write function was aborted because 
timeout expired while function was in progress. 


See Also viSetBuf 
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Syntax 

Description 

Parameters 


VISA Language Reference 

viGetAttribute 


viGetAttribute 

viGetAttribute(ViSession/ViEvent/ViFindList VI, 
ViAttr attribute, ViAttrState attrState) ; 

This function retrieves the state of an attribute for the specified session. 


Name 

Direction 

Type 

Description 

attribute 

IN 

ViAttr 

Resource attribute for which the state 
query is made. 

attrState 

OUT 

See Note 
below. 

The state of the queried attribute for a 
specified resource. The interpretation of 
the returned value is defined by the 
individual resource. Note that you must 
allocate space for character strings 
returned. 

vi 

IN 

ViSession 

Vi Event 

ViFindList 

Unique logical identifier to a session, 
event, or find list. 


NOTE 

The pointer passed to viGetAttribute must point to the exact type 
required for that attribute, ViUlntl6, Vilnt32, etc. For example, when 
reading an attribute state that returns a ViChar, you must pass a pointer 
to a ViChar variable. You must allocate space for the returned data. 
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VISA Language Reference 

viGetAttribute 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Resource attribute retrieved successfully. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP ATTR 

The specified attribute is not defined by the 
referenced resource. 


See Also viSetAttribute 
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Syntax 

Description 

Parameters 


Return Values 


VISA Language Reference 

viGpibCommand 


viGpibCommand 

viGpibCommand (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retCount ) ; 


Write GPIB command bytes on the bus. This operation attempts to write 
count number of bytes of GPIB commands to the interface bus specified by 
vi. This operation is valid only on GPIB INTFC (interface) sessions. This 
operation returns only when the transfer terminates. 

If you pass VI_NULL as the retCount parameter to the viGpibCommand 
operation, the number of bytes transferred will not be returned. This may be 
useful if it is important to know only whether the operation succeeded or 
failed. 


Name 

Direction 

Type 

Description 

buf 

IN 

ViBuf 

Buffer containing valid GPIB commands. 

count 

IN 

ViUInt32 

Number of bytes to be written. 

retCount 

IN 

ViUInt32 

Number of bytes actually transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Value for retCount Parameter 


Value 

Action Description 

VI NULL 

Do not return the number of bytes transferred. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Resource attribute retrieved successfully. 
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VISA Language Reference 

viGpibCommand 


See Also 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start write operation because setup 
is invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during 
transfer. 

VI ERROR NCIC 

The interface associated with this session 
is not currently the controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both 

NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before operation completed. 


INTFC Resource Description 
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Syntax 

Description 


Parameters 


VISA Language Reference 

viGpibControlATN 


viGpibControlATN 

viGpibControlATN (ViSession vi, ViUIntl6 mode); 


Controls the state of the GPIB ATN interface line, and optionally the active 
controller state of the local interface board. This operation asserts or 
deasserts the GPIB ATN interface line according to the specified mode. 

The mode can also specify whether the local interface board should acquire 
or release Controller Active status. This operation is valid only on GPIB 
INTFC (interface) sessions. 


NOTE 

It is generally not necessary to use the viGpibControlATN operation in 
most applications. Other operations such as viGpibCommand and 
viGpibPassControl modify the ATN and/or CIC state automatically. 


Name 

Direction 

Type 

Description 

mode 

IN 

ViUIntl6 

Specifies the state of the ATN line and, 
optionally, the local active controller 
state. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Values for mode Parameter 


mode 

Action Description 

VI GPIB ATN ASSERT 

Assert ATN line synchronously (in 488 
terminology). If a data handshake is in 
progress, ATN will not be asserted until the 
handshake is complete. 

VI GPIB ATN DEASSERT 

Deassert ATN line. 

VI GPIB ATN DEASSERT 

HANDSHAKE* 

Deassert ATN line, and enter shadow 
handshake mode. The local board will 
participate in data handshakes as an 
Acceptor without actually reading the data. 
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VISA Language Reference 

viGpibControlATN 


Return Values 


See Also 


mode 

Action Description 

VI GPIB REN ASSERT 

IMMEDIATE* 

Assert ATN line asynchronously (in 488 
terminology). This should generally be 
used only under error conditions. 


* Not supported in Agilent VISA 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR INV MODE 

The value specified by the mode parameter 
is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NCIC 

The interface associated with this session 
is not currently the controller in charge. 

VI ERROR NSUP MODE 

The specified mode is not supported by this 
VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 
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Syntax 

Description 


Parameters 


VISA Language Reference 

viGpibControlREN 


viGpibControlREN 

viGpibControlREN (ViSession vi, ViUIntl6 mode); 

Controls the state of the GPIB REN interface line and, optionally, the 
remote/local state of the device. This operation asserts ordeasserts the 
GPIB REN interface line according to the specified mode. 

The mode can also specify whether the device associated with this session 
should be placed in local state (before deasserting REN) or remote state 
(after asserting REN). This operation is valid only if the GPIB interface 
associated with the session specified by vi is currently the system controller. 

An INSTR resource implementation of viGpibControlREN for a 
GPIB System supports all documented modes. An INTFC resource 
implementation of viGpibControlREN for a GPIB System supports 
the modes vi_gpib_ren_deassert, vi_gpib_ren_assert, and 

VI GPIB REN ASSERT LLO. 


Name 

Direction 

Type 

Description 

mode 

IN 

ViUIntl6 

Specifies the state of the REN line and, 
optionally, the device remote/local state. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Values for mode Parameter 


mode 

Action Description 

VI GPIB REN ADDRESS GTL 

Send the Go To Local command (GTL) 
to this device. 

VI GPIB REN ASSERT 

Assert REN line. 

VI GPIB REN ASSERT ADDRESS 

Assert REN line and address this device. 

VI GPIB REN ASSERT ADDRESS 

LLO 

Address this device and send it LLO, 
putting it in RWLS. 

VI GPIB REN ASSERT LLO 

Send LLO to any devices that are 
addressed to listen. 
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VISA Language Reference 

viGpibControlREN 


mode 

Action Description 

VI GPIB REN DEASSERT 

Deassert REN line. 

VI GPIB REN DEASSERT GTL 

Send the Go To Local command (GTL) 
to this device and deassert REN line. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Resource attribute retrieved successfully. 


Error Codes 

Description 

VI ERROR INV MODE 

The value specified by the mode parameter 
is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NCIC 

The interface associated with this session 
is not currently the controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both 

NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR NSYS CNTLR 

The interface associated with this session 
is not the system controller. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 
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VISA Language Reference 

viGpibPassControl 


viGpibPassControl 

Syntax viGpibPassControl (ViSession vi, ViUIntl6 primAddr, 

ViUIntl6 secAddr) ; 

Description Tell the GPIB device at the specified address to become controller in charge 

(CIC). This operation passes controller in charge status to the device 
indicated by primAddr and secAddr and then deasserts the ATN line. 

This operation assumes that the targeted device has controller capability. 
This operation is valid only on GPIB INTFC (interface) sessions. 

Parameters 


Name 

Direction 

Type 

Description 

primAddr 

IN 

ViUIntl6 

Primary address of the GPIB device to 
which you want to pass control. 

secAddr 

IN 

ViUIntl6 

Secondary address of the targeted 

GPIB device. If the targeted device 
does not have a secondary address, 
this parameter should contain the value 
VI NO SEC ADDR. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 
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VISA Language Reference 

viGpibPassControl 


See Also 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR 10 

An unknown I/O error occurred during 
transfer. 

VI ERROR NCIC 

The interface associated with this session 
is not currently the controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both 

NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before operation completed. 
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Syntax 

Description 

Parameters 

Return Values 


See Also 


VISA Language Reference 

viGpibSendIFC 


viGpibSendIFC 

viGpibSendIFC (ViSession vi) ; 


Pulse the interface clear line (IFC) for at least 100 (iseconds. This operation 
asserts the IFC line and becomes controller in charge (CIC). The local 
board must be the system controller. This operation is valid only on GPIB 
INTFC (interface) sessions. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR NSYS CNTLR 

The interface associated with this session 
is not the system controller. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


INTFC Resource Description 
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Syntax 


Description 


VISA Language Reference 

viln8, viln 16, and viln32 


viln8, viln16, and viln32 

viln8 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUInt8 val8) ; 

vilnl6 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUIntl6 vail6) ; 

viln32 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUInt32 val32) ; 

This operation, by using the specified address space, reads in 8, 16, or 32 
bits of data from the specified offset. This operation does not require 
viMapAddress to be called prior to its invocation. 

This function reads in an 8-bit, 16-bit, or 32-bit value from the specified 
memory space (assigned memory base + offset). This function takes the 
8-bit, 16-bit, or 32-bit value from the address space pointed to by space. 

The offset must be a valid memory address in the space. This function does 
not require viMapAddress to be called prior to its invocation. 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameter specifies a relative offset from the start of the instrument’s 
address space. If the viSession parameter (vi) refers to a MEMACC 
session, the offset parameter is an absolute offset from the start of memory 
in that VXI address space. The valid entries for specifying address space 
are: 


Value 

Description 

VI A16 SPACE 

Address the A16 address space of VXI/MXI bus. 

VI A24 SPACE 

Address the A24 address space of VXI/MXI bus. 

VI A32 SPACE 

Address the A32 address space of VXI/MXI bus. 


The high-level operations viln8, vilnl6, and viln32 operate 
successfully independently from the low-level operations (viMapAddress, 
viPeek8, viPeekl6, viPeek32, viPoke8, viPokel6, and 
viPoke32). The high-level and low-level operations should operate 
independently regardless of the configured state of the hardware that is 
used to perform memory accesses. 
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viln8, vilnl 6, and viln32 


For an INSTR resource, the offset is a relative address of the device 
associated with the given INSTR resource. For a MEMACC resource, the 
offset parameter specifies an absolute address. 

The offset specified in the viln8, vilnl6, and viln32 operations for an 
INSTR resource is the offset address relative to the device's allocated 
address base for the corresponding address space specified. 

For example, if space specifies vi_a16_space, offset specifies the offset 
from the logical address base address of the VXI device specified. If space 
specifies vi_a24_space or vi_a32_space, offset specifies the offset 
from the base address of the VXI device's memory space allocated by the 
VXI Resource Manager within VXI A24 or A32 space. 


Parameters 


Name 

Direction 

Type 

Description 

offset 

IN 

ViBusAddress 

Offset (in bytes) of the memory 
to read from. 

space 

IN 

ViUIntl6 

Specifies the address space. 

(See the following table.) 

val8, vail6, 
or val32 

OUT 

ViUInt8, 
ViUIntl6 , or 
ViUInt32 

Data read from bus (8-bits for 
viin8, 16-bits for viinl6, and 
32-bits for viln32). 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 
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VISA Language Reference 

viln8, viln 16, and viln32 


See Also 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN 

OFFSET 

The specified offset is not properly aligned for the 
access width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this 
hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


viOut8, viOut16, viOut32, viPeek8, viPeek16, viPeek32, viMoveln8, viMoveln16, 
viMoveln32 
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Syntax 

Description 


Parameters 


VISA Language Reference 

vilnstallHandler 


vilnstallHandler 

vilnstallHandler (ViSession vi, ViEventType eventType, 
ViHndlr handler, ViAddr userHandle) ; 


This function allows applications to install handlers on sessions for event 
callbacks. The handler specified in the handler parameter is installed along 
with previously installed handlers for the specified event. Applications can 
specify a value in the userHandle parameter that is passed to the handler on 
its invocation. VISA identifies handlers uniquely using the handler reference 
and the userHandle value. 


NOTE 

Versions of VISA prior to Version 2.0 allow only a single handler per 
event type per session. 


Name 

Direction 

Type 

Description 

eventType 

IN 

ViEventType 

Logical event identifier. 

handler 

IN 

ViHndlr 

Interpreted as a valid reference to a 
handler to be installed by an 
application. 

userHandle 

IN 

ViAddr 

A value specified by an application 
that can be used for identifying 
handlers uniquely for an event type. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


The following events can be enabled: 


Event Name 

Description 

VI EVENT 10 COMPLETION 

Notification that an asynchronous operation has 
completed. 

VI EVENT SERVICE REQ 

Notification that a device is requesting service. 
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VISA Language Reference 

vilnstallHandler 


Return Values 


See Also 


Event Name 

Description 

VI EVENT TRIG 

Notification that a hardware trigger was 
received from a device. 

VI EVENT VXI SIGP 

Notification that a VXI signal or VXI interrupt 
has been received from a device. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Event handler installed successfully. 


Error Codes 

Description 

VI ERROR HNDLR NINSTALLED 

The handler was not installed. This may be 
returned if an application attempts to install 
multiple handlers for the same event on the 
same session. 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV HNDLR REF 

The given handler reference is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 


viEventHandler 
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Syntax 


Description 


VISA Language Reference 

viLock 


viLock 

viLock (ViSession vi , ViAccessMode lockType, ViUInt32 
timeout, ViKeyld requestedKey, ViKeyld access Key) ; 


NOTE 

The viLock function is not supported on network devices. 


This function is used to obtain a lock on the specified resource. The caller 
can specify the type of lock requested (exclusive or shared lock) and the 
length of time the operation will suspend while waiting to acquire the lock 
before timing out. This function can also be used for sharing and nesting 
locks. 

The requestedKey and accessKey parameters apply only to shared locks. 
These parameters are not applicable when using the lock type 
vi_excluSIve_lock . In this case, requestedKey and accessKey should 
be set to vi_null. VISA allows user applications to specify a key to be 
used for lock sharing through the use of the requestedKey parameter. 

Alternatively, a user application can pass vi_null for the requestedKey 
parameter when obtaining a shared lock, in which case VISA will generate a 
unique access key and return it through the accessKey parameter. If a user 
application does specify a requestedKey value, VISA will try to use this 
value for the accessKey. 

As long as the resource is not locked, VISA will use the requestedKey as 
the access key and grant the lock. When the operation succeeds, the 
requestedKey will be copied into the user buffer referred to by the 
accessKey parameter. 

The session that gained a shared lock can pass the accessKey to other 
sessions for the purpose of sharing the lock. The session wanting to join the 
group of sessions sharing the lock can use the key as an input value to the 
requestedKey parameter. 

VISA will add the session to the list of sessions sharing the lock, as long as 
the requestedKey v alue matches the accessKey value for the particular 
resource. The session obtaining a shared lock in this manner will then have 
the same access privileges as the original session that obtained the lock. 


212 


Chapter 7 




VISA Language Reference 

viLock 


It is also possible to obtain nested locks through this function. To acquire 
nested locks, invoke the viLock function with the same lock type as the 
previous invocation of this function. For each session, viLock and 
viUnlock share a lock count, which is initialized to 0. Each invocation of 
viLock for the same session (and for the same lockType) increases the 
lock count. 

A shared lock returns with the same accessKey every time. When a session 
locks the resource a multiple number of times, it is necessary to invoke the 
viUnlock function an equal number of times in order to unlock the 
resource. That is, the lock count increments for each invocation of viLock, 
and decrements for each invocation of viUnlock. A resource is actually 
unlocked only when the lock count is 0. 


NOTE 

On HP-UX, SIGALRM is used in implementing the viLock when timeout 
is non-zero. The viLock function's use of SIGALRM is exclusive - an 
application should not also expect to use SIGALRM at the same time. 


NOTE 

On HP-UX, some semaphores used in locking are permanently allocated 
and diminish the number of semaphores available for applications. If the 
operating system runs out of semaphores, the number of semaphores 
may be increased by doing the following: 

1 . Run sam. 

2. Double-click Kernel Configuration. 

3. Double-click Configurable Parameters. 

4. Change semmni and semmns to a higher value, such as 300. 
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VISA Language Reference 

viLock 


Parameters 


Name 

Direction 

Type 

Description 

accessKey 

OUT 

ViKeyld 

This parameter should be set to 
vi null when lockType is 
vi exclusive lock (exclusive 
lock). 




When trying to lock the resource as 
vi shared lock (shared lock), the 
resource returns a unique access key 
for the lock if the operation succeeds. 
This accessKey can then be passed 
to other sessions to share the lock. 

tockType 

IN 

ViAc ce s sMode 

Specifies the type of lock requested, 
which can be vi exclusive lock 

or VI SHARED LOCK. 

requestedKey 

IN 

ViKeyld 

This parameter is not used and should 
be set to vi null when lockType 
is vi exclusive lock (exclusive 
lock). 




When trying to lock the resource as 
vi shared lock (shared lock), a 
session can either set it to vi null 
so that VISA generates an accessKey 
for the session, or the session can 
suggest an accessKey to use for the 
shared lock. See "Description" for 
more details. 

timeout 

IN 

ViUInt32 

Absolute time period (in milliseconds) 
that a resource waits to get unlocked 
by the locking session before 
returning this operation with an error. 
VI TMO IMMEDIATE and 
vi tmo infinite are also valid 
values. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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Return Values 


See Also 


VISA Language Reference 

viLock 


Type ViStatus This is the function return status. It returns either a 

completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

The specified access mode was successfully 
acquired. 

VI SUCCESS NESTED 

EXCLUSIVE 

The specified access mode was successfully 
acquired, and this session has nested exclusive 
locks. 

VI SUCCESS NESTED 

SHARED 

The specifed access mode was successfully 
acquired, and this session has nested shared 
locks. 


Error Codes 

Description 

VI ERROR INV ACCESS KEY 

The requestedKey value passed is not a valid 
access key to the specified resource. 

VI ERROR INV LOCK TYPE 

The specified type of lock is not supported by 
this resource. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given vi does not identify a valid session or 
object. 

VI ERROR RSRC LOCKED 

The specified type of lock cannot be obtained 
because the resource is already locked with a 
lock type incompatible with the lock requested. 

VI ERROR TMO 

The specified type of lock could not be obtained 
within the specified timeout period. 


villnlock. For more information on locking, see Chapter 4 - Programming with 
VISA. 
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Syntax 


Description 


VISA Language Reference 

viMapAddress 


vi Map Address 

viMapAddress(ViSession vi, ViUIntl6 mapSpace, 
ViBusAddress mapBase , ViBusSize mapSize, 
ViBoolean access, ViAddr suggested, ViAddr address) ; 


This function maps in a specified memory space. The memory space that is 
mapped is dependent on the type of interface specified by the vi parameter 
and the mapSpace parameter (see the following table). The address 
parameter returns the address in your process space where memory is 
mapped. The values for the mapSpace parameter are: 


Value 

Description 

VI A16 SPACE 

Map the A16 address space of VXI/MXI bus. 

VI A24 SPACE 

Map the A24 address space of VXI/MXI bus. 

VI A32 SPACE 

Map the A32 address space of VXI/MXI bus. 


If the viSession parameter (vi) refers to an INSTR session, the mapBase 
parameter specifies a relative offset in the instrument’s mapSpace. If the 
viSession parameter (vi) refers to a MEMACC session, the mapBase 
parameter is an absolute offset from the start of the VXI mapSpace. 


NOTE 

For a given session, you can only have one map at one time. If you need 
to have multiple maps to a device, you must open one session for each 
map needed. 


The mapBase parameter specified in the viMapAddress operation for an 
INSTR resource is the offset address relative to the device's allocated 
address base for the corresponding address space specified. 

For example, if mapSpace specifies vi_a16_space, mapBase specifies 
the offset from the logical address base address of the VXI device specified. 
If mapSpace specifies vi_a24_space or vi_a32_space, mapBase 
specifies the offset from the base address of the VXI device's memory space 
allocated by the VXI Resource Manager within VXI A24 or A32 space. 
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VISA Language Reference 

viMapAddress 


Parameters 


Name 

Direction 

Type 

Description 

access 

IN 

ViBoolean 

VI FALSE. 

address 

OUT 

ViAddr 

Address in your process space 
where the memory was mapped. 

mapBase 

IN 

ViBusAddress 

Offset (in bytes) of the memory to 
be mapped. 

map Size 

IN 

ViBusSize 

Amount of memory to map (in 
bytes). 

mapSpace 

IN 

ViUIntl6 

Specifies the address space to 
map. 

suggested 

IN 

ViAddr 

If suggested parameter is not 
vi null, the operating system 
attempts to map the memory to the 
address specified in suggested. 
There is no guarantee, however, 
that the memory will be mapped to 
that address. This function may 
map the memory into an address 
region different from suggested. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 

completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Map successful. 
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VISA Language Reference 

viMapAddress 


Error Codes 

Description 

VI ERROR ALLOC 

Unable to allocate window of at least the 
requested size. 

VI ERROR INV ACC MODE 

Invalid access mode. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because the setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR INV SIZE 

Invalid size of window specified. 

VI ERROR INV SPACE 

Invalid mapSpace specified. 

VI ERROR NSUP OFFSET 

Specified region is not accessible from this 
hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

viMapAddress could not acquire resource or 
perform mapping before the timer expired. 

VI ERROR WINDOW MAPPED 

The specified session already contains a mapped 
window. 


See Also 


villnmapAddress 
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VISA Language Reference 

viMapTrigger 


Syntax 

Description 


Parameters 


viMapTrigger 

viMapTrigger(ViSession vi , Vilntl6 trigSrc, 
Vi Inti 6 trigDest, ViUIntl6 mode) ; 


Map the specified trigger source line to the specified destination line. This 
operation can be used to map one trigger line to another. This operation is 
valid only on VXI Backplane (BACKPLANE) sessions. 

If this operation is called multiple times on the same BACKPLANE resource 
with the same source trigger line and different destination trigger lines, the 
result should be that when the source trigger line is asserted all specified 
destination trigger lines should also be asserted. 

If this operation is called multiple times on the same BACKPLANE resource 
with different source trigger lines and the same destination trigger line the 
result should be that when any of the specified source trigger lines is 
asserted, the destination trigger line should also be asserted. However, 
mapping a trigger line (as either source or destination) multiple times 
requires special hardware capabilities and is not guaranteed to be 
implemented. 


Name 

Direction 

Type 

Description 

mode 

IN 

ViUIntl6 

Specifies the trigger mapping 
mode. This should always be 
vi null for VISA 2.2. 

trigDest 

IN 

Vilntl6 

Destination line to which to map. 

trigSrc 

IN 

Vilntl6 

Source line from which to map. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 
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VISA Language Reference 

viMapTrigger 


Special Values for trgSrc and trigDest Parameters 


Value 

Action Description 

VI TRIG ECLO - 

VI TRIG ECL1 

Map the specified VXI ECL trigger line. 

VI TRIG PANEL IN 

Map controller's front panel trigger input line. 

VI TRIG PANEL OUT 

Map controller's front panel trigger output line. 

VI TRIG TTLO - 

VI TRIG TTL7 

Map the specified VXI TTL trigger line. 


Return Values 


Type ViStatus This is the function return status. It returns either a 

completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 

VI SUCCESS TRIG MAPPED 

Path from trigSrc to trigDest is already mapped. 


Error Codes 

Description 

VI ERROR INV LINE 

Specified line(s) ( trigSrc or trigDest) invalid. 

VI ERROR INV MODE 

Value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR LINE IN USE 

One of the specified lines ( trigSrc or trigDest) is 
currently in use. 

VI ERROR NSUP LINE 

One of the specified lines ( trigSrc or trigDest) is 
not supported by this VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before operation completed. 


See Also BACKPLANE Resource Description 
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VISA Language Reference 

viMemAlloc 


Syntax 


Description 


Parameters 


Return Values 


viMemAlloc 

viMemAlloc(ViSession vi, ViBusSize size, 
ViBusAddress offset) ; 


NOTE 

This function is not implemented in Agilent VISA. 


This function returns an offset into a device's memory region that has been 
allocated for use by this session. If the device to which the given vi refers is 
located on the local interface card, the memory can be allocated either on 
the device itself or on the computer's system memory. The offset returned 
from the viMemAlloc operation is the offset address relative to the device's 
allocated address base for whichever address space into which the given 
device exports memory. 


Name 

Direction 

Type 

Description 

offset 

OUT 

ViBusAddress 

Returns the offset of the allocated 
device memory. 

size 

IN 

ViBusSize 

Specifies the size of the allocation. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

The operation completed successfully. 
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VISA Language Reference 

viMemAlloc 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

Unable to allocate shared memory block of the 
requested size. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SIZE 

Invalid size specified. 

VI ERROR MEM NSHARED 

The device does not export any memory. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because 
the resource identified by vi has been locked for this 
kind of access. 


viMemFree 
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VISA Language Reference 

viMemFree 


Syntax 

Description 

Parameters 


Return Values 


See Also 


viMemFree 

viMemFree (ViSession vi, ViBusAddress offset); 

NOTE 

This function is not implemented in Agilent VISA. 

This function frees the memory previously allocated using viMemAlloc. 


Name 

Direction 

Type 

Description 

offset 

IN 

ViBusAddress 

Specifies the memory previously 
allocated with viMemAlloc. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 

completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

The operation completed successfully. 


Error Codes 

Description 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR WINDOW NMAPPED 

The specified offset is currently in use by 
viMapAddre s s. 


viMemAlloc 
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Syntax 


Description 


VISA Language Reference 

viMove 


viMove 

viMove (ViSession vi , ViUIntl6 srcSpace, 
ViBusAddress srcOffset , ViUIntl6 srcWidth, 
ViUIntl6 destSpace , ViBusAddress destOffset, 
ViUIntl6 destWidth, ViBusSize length) ; 


This operation moves data from the specified source to the specified 
destination. The source and the destination can either be local memory or 
the offset of the interface with which this INSTR or MEMACC resource is 
associated. This operation uses the specified data width and address space. 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameters specify relative offsets from the start of the instrument’s address 
space. If the viSession parameter (vi) refers to a MEMACC session, the 
offset parameters are absolute offsets from the start of memory in the 
specified VXI address space. 

Valid entries for specifying address space: 


Value 

Description 

VI A16 SPACE 

Address A16 memory address space of the VXI/MXI bus. 

VI A24 SPACE 

Address A24 memory address space of the VXI/MXI bus. 

VI A32 SPACE 

Address A32 memory address space of the VXI/MXI bus. 

VI LOCAL SPACE 

Address the process-local memory (using virtual address). 


Valid entries for specifying widths: 


Value 

Description 

VI WIDTH 8 

Performs an 8-bit (D08) transfer. 

VI WIDTH 16 

Performs a 16-bit (D16) transfer. 

VI WIDTH 32 

Performs a 32-bit (D32) transfer. 
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VISA Language Reference 

viMove 


The high-level operation viMove operates successfully independently from 
the low-level operations (viMapAddress, viPeek8, viPeekl6, 
viPeek32 , viPoke8 , viPokel6, and viPoke32). The high-level and 
low-level operations should operate independently regardless of the 
configured state of the hardware that is used to perform memory accesses. 

The length specified in the viMove operation is the number of elements 
(of the size corresponding to the operation) to transfer, beginning at the 
specified offset. Therefore, offset + length*size cannot exceed the amount 
of memory exported by the device in the given space. 

If srcSpace is not vi_local_space, srcOffset is a relative address of the 
device associated with the given INSTR resource. Similarly, if destspace is 
not vi_local_space, destOffset is a relative address of the device 
associated with the given INSTR resource. srcOffset and destOffset 
specified in the viMove operation for a MEMACC resource are absolute 
addresses. 


Parameters 


Name 

Direction 

Type 

Description 

destOffset 

IN 

ViBusAddress 

Specifies the address space of the 
destination 

destSpace 

IN 

ViUIntl6 

Specifies the address space of the 
destination. 

destWidth 

IN 

ViUIntl6 

Specifies the data width of the 
destination. 

length 

IN 

ViBusSize 

Number of data elements to 
transfer, where the data width of the 
elements to transfer is identical to 
the source data width. 

srcOffset 

IN 

ViBusAddress 

Offset of the starting address or 
register from which to read. 

srcSpace 

IN 

ViUIntl6 

Specifies the address space of the 
source. 

srcWidth 

IN 

ViUIntl6 

Specifies the data width of the 
source. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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Return Values 


See Also 


VISA Language Reference 

viMove 


Type ViStatus This is the operational return status. It returns either a 

completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus Error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OFFSET 

Invalid source or destination offset 
specified. 

VI ERROR INV SESSION 

VI ERROR OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR INV SPACE 

Invalid source or destination address 
specified. 

VI ERROR INV WIDTH 

Invalid source or destination width 
specified. 

VI ERROR NSUP ALIGH OFFSET 

The specified offset is not properly aligned 
for the access width of the operation. 

VI ERROR NSUP OFFSET 

Specified source or destination offset is not 
accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this 
operation. 

VI ERROR NSUP VAR WIDTH 

Cannot support source and destination 
widths that are different. 

VI ERROR NSUP WIDTH 

Specified width is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


viMoveAsync. Also, see MEMACC Resource Description. 
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VISA Language Reference 

viMoveAsync 


Syntax 


Description 


viMoveAsync 

viMoveAsync (ViSession vi, ViUIntl6 srcSpace, 
ViBusAddress srcOffset , ViUIntl6 srcWidth, 

ViUIntl6 destSpace , ViBusAddress destOffset, 
ViUIntl6 destWidth, ViBusSize length, Vi Job Id jobld) ; 


NOTE 

This function is implemented synchronously in Agilent VISA. 


This operation asynchronously moves data from the specified source to the 
specified destination. This operation queues up the transfer in the system, 
then it returns immediately without waiting for the transfer to complete. 
When the transfer terminates, a vi_event_io_complete event indicates 
the status of the transfer. 

The operation returns jobld which you can use either with viTerminate to 
abort the operation or with vi_event_io_completion events to identify 
which asynchronous move operations completed. The source and 
destination can be either local memory or the offset of the device/interface 
with which this INSTR or MEMACC Resource is associated. This operation 
uses the specified data width and address space. 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameters specify relative offsets from the start of the instrument’s address 
space. If the viSession parameter (vi) refers to a MEMACC session, the 
offset parameters are absolute offsets from the start of memory in the 
specified VXI address space. Valid entries for specifying address space: 


Value 

Description 

VI A16 SPACE 

Address A16 memory address space of the VXI/MXI bus. 

VI A24 SPACE 

Address A24 memory address space of the VXI/MXI bus. 

VI A32 SPACE 

Address A32 memory address space of the VXI/MXI bus. 

VI LOCAL SPACE 

Addresses the process-local memory (using virtual 
address). 
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viMoveAsync 


Valid entries for specifying widths: 


Value 

Description 

VI WIDTH 8 

Performs an 8-bit (D08) transfer. 

VI WIDTH 16 

Performs a 16-bit (D16) transfer. 

VI WIDTH 32 

Performs a 32-bit (D32) transfer. 


Since an asynchronous I/O request could complete before the 
viMoveAsync operation returns, and the I/O completion event can be 
distinguished based on the job identifier, an application must be made aware 
of the job identifier before the first moment that the I/O completion event 
could possibly occur. Setting the output parameter jobld before the data 
transfer even begins ensures that an application can always match the jobld 
parameter with the vi_attr_job_id attribute of the I/O completion event. 

If you pass VI_NULL as the jobld parameter to the viMoveAsync 
operation, no jobld will be returned. This option may be useful if only one 
asynchronous operation will be pending at a given time. If multiple jobs are 
queued at the same time on the same session, an application can use the 
jobld to distinguish the jobs, as they are unique within a session. The value 
VI_NULL is a reserved jobld and has a special meaning in viTerminate. 

The status code vi_error_rsrc_locked can be returned either 
immediately or from the vi_event_io_completion event. 

If srcSpace is not vi_local_space, srcOffset is a relative address of the 
device associated with the given INSTR resource. Similarly, if destspace is 
not vi_local_space, destOffset is a relative address of the device 
associated with the given INSTR resource. 


Parameters 


Name 

Direction 

Type 

Description 

destOffset 

IN 

ViBusAddress 

Offset of the starting address or 
register to write to. 

destSpace 

IN 

ViUIntl6 

Specifies the address space of the 
destination. 

destWidth 

IN 

ViUIntl6 

Specifies the data width of the 
destination. 
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viMoveAsync 


Name 

Direction 

Type 

Description 

jobld 

OUT 

ViJobld 

Represents the location of an 
integer that will be set to the job 
identifier of this asynchronous 
move operation. Each time an 
asynchronous move operation is 
called, it is assigned a unique job 
identifier. 

length 

IN 

ViBusSize 

Number of data elements to 
transfer, where the data width of 
the elements to transfer is identical 
to the source data width. 

srcOffset 

IN 

ViBusAddress 

Offset of the starting address or 
register from which to read. 

srcSpace 

IN 

ViUIntl6 

Specifies the address space of the 
source. 

srcWidth 

IN 

ViUIntl6 

Specifies the data width of the 
source. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 


Special value for jobld Parameter 


Value 

Description 

VI NULL 

Operation does not return a job identifier. 


Return Values 

Type ViStatus This is the operational return status. It returns either a 

completion code or an error code as follows. 


Completion Codes 

Description 

VI_SUCCESS 

Asynchronous operation completed successfully. 

VI SUCCESS SYNC 

Operation Perfomed synchronously. 
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viMoveAsync 


See Also 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR QUEUE 

Unable to queue move operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


viMove. Also, see the INSTR and MEMACC Resource descriptions. 
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viMoveln8, viMoveln16, and viMoveln32 


Syntax 


Description 


viMoveln8, viMoveln16, and viMoveln32 

viMoveIn8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViBusSize length, ViAUlnt8 buf8) ; 

viMovelnl6(ViSession vi, ViUIntl6 space, 

ViBusAddress offset, ViBusSize length, ViAUIntl6 buf16) ; 

viMoveIn32(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViBusSize length, ViAUInt32 buf32) ; 


This function moves an 8-bit, 16-bit, or 32-bit block of data from the specified 
memory space (assigned memory base + offset) to local memory. This 
function reads the 8-bit, 16-bit, or 32-bit value from the address space 
pointed to by space. The offset must be a valid memory address in the 
space. These functions do not require viMapAddress to be called prior to 
their invocation. 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameters specify relative offsets from the start of the instrument’s address 
space. If the viSession parameter (vi) refers to a MEMACC session, the 
offset parameters are absolute offsets from the start of memory in the 
specified VXI address space. The valid entries for specifying address space 
are: 


Value 

Description 

VI A16 SPACE 

Address the A16 address space of VXI/MXI bus. 

VI A24 SPACE 

Address the A24 address space of VXI/MXI bus. 

VI A32 SPACE 

Address the A32 address space of VXI/MXI bus. 


The viMoveln functions do a block move of memory from a VXI device 
if VI_ATTR_SRC_INCREMENT is 1. However, they do a FIFO read of a VXI 
memory location if vi_attr_src_increment is 0 (zero). 

The high-level operations viln8, vilnl6, and viln32 operate 
successfully independently from the low-level operations (viMapAddress, 
viPeek8, viPeekl6, viPeek32, viPoke8, viPokel6, and 
viPoke32). 
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viMoveln8, viMoveln16, and viMoveln32 


The high-level and low-level operations should operate independently 
regardless of the configured state of the hardware that is used to perform 
memory accesses. 

For an INSTR resource, the offset is a relative address of the device 
associated with the given INSTR resource. For a MEMACC resource, the 
offset parameter specifies an absolute address. 

The offset specified in the viMoveln8, viMovelnl6, and viMoveln32 
operations for an INSTR resource is the offset address relative to the 
device's allocated address base for the corresponding address space 
specified. 

For example, if space specifies vi_a16_space, offset specifies the offset 
from the logical address base address of the VXI device specified. If space 
specifies vi_a24_space or vi_a32_space, offset specifies the offset 
from the base address of the VXI device's memory space allocated by the 
VXI Resource Manager within VXI A24 or A32 space. 

The length specified in the viMoveinXX operations is the number of 
elements (of the size corresponding to the operation) to transfer, beginning 
at the specified offset. Therefore, offset + length*size cannot exceed the 
amount of memory exported by the device in the given space. 

The length specified in the viMoveinXX operations is the number of 
elements (of the size corresponding to the operation) to transfer, beginning 
at the specified offset. Therefore, offset + length*size cannot exceed the 
total amount of memory available in the given space. 


Parameters 


Name 

Direction 

Type 

Description 

bum, 
bufl 6, 

or 

buf32 

OUT 

ViAUInt8, 
ViAUIntl6, or 
ViAUInt32 

Data read from bus (8-bits for 
viMoveIn8, 16-bits for 
viMoveinl6, and 32-bits for 
viMoveIn32). 

length 

IN 

ViBusSize 

Number of elements to transfer, 
where the data width of the elements 
to transfer is 8-bits for viMoveinS, 
16-bits for viMoveinl6, or 32-bits 
for viMoveIn32. 

offset 

IN 

ViBu sAddre s s 

Offset (in bytes) of the starting 
address or register to read from. 
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viMoveln8, viMoveln16, and viMoveln32 


Name 

Direction 

Type 

Description 

space 

IN 

ViUIntl6 

Specifies the address space. (See 
the following table.) 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid 
(due to attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN 

OFFSET 

The specified offset is not properly aligned for the 
access width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because 
the resource identified by vi has been locked for this 
kind of access. 


See Also viMoveOut8, viMoveOut16, viMoveOut32, viln8, viln16, viln32 
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viMoveOut8, viMoveOut16, and viMoveOut32 


viMoveOut8, viMoveOut16, and 
viMoveOut32 


Syntax 


Description 


viMoveOut8(ViSession vi, ViUIntl6 space, ViBusAddress 
offset, ViBusSize length, ViAUInt8 buf8) ; 


viMoveOutl 6 (ViSession vi, 
offset, ViBusSize length, 


ViUIntl6 space, ViBusAddress 
ViAUIntl6 buf16) ; 


viMoveOut32(ViSession vi, 
offset, ViBusSize length, 


ViUIntl6 space, ViBusAddress 
ViAUInt32 buf32) ; 


This function moves an 8-bit, 16-bit, or 32-bit block of data from local 
memory to the specified memory space (assigned memory base + offset). 
This function writes the 8-bit, 16-bit, or 32-bit value to the address space 
pointed to by space. The offset must be a valid memory address in the 
space. This function does not require viMapAddress to be called prior to 
its invocation 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameters specify relative offsets from the start of the instrument’s address 
space. If the viSession parameter (vi) refers to a MEMACC session, the 
offset parameters are absolute offsets from the start of memory in the 
specified VXI address space. The valid entries for specifying address space 
are: 


Value 

Description 

VI A16 SPACE 

Address the A16 address space of VXI/MXI bus. 

VI A24 SPACE 

Address the A24 address space of VXI/MXI bus. 

VI A32 SPACE 

Address the A32 address space of VXI/MXI bus. 


The viMoveOut functions do a block move of memory from a VXI device if 
VI_ATTR_DEST_INCREMENT is 1. However, they do a FIFO read of a VXI 
memory location if vi_attr_dest_increment is 0 (zero). 

The offset specified in the viMoveOut8, viMoveOutl6, and 
viMoveOut32 operations for an INSTR resource is the offset address 
relative to the device's allocated address base for the corresponding 
address space specified. 
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viMoveOut8, viMoveOut16, and viMoveOut32 


For example, if space specifies vi_a16_space, offset specifies the offset 
from the logical address base address of the VXI device specified. If space 
specifies vi_a24_space or vi_a32_space, offset specifies the offset 
from the base address of the VXI device's memory space allocated by the 
VXI Resource Manager within VXI A24 or A32 space. 

The length specified in the viMoveOutxx operations is the number of 
elements (of the size corresponding to the operation) to transfer, beginning 
at the specified offset. Therefore, offset + length*size cannot exceed the 
amount of memory exported by the device in the given space. 

The length specified in the viMoveOutxx operations is the number of 
elements (of the size corresponding to the operation) to transfer, beginning 
at the specified offset. Therefore, offset + length*size cannot exceed the 
total amount of memory available in the given space. 


Parameters 


Name 

Direction 

Type 

Description 

buf8, 
bufl 6, 

or 

buf32 

IN 

ViAUInt8, 
ViAUIntl6, or 
ViAUInt32 

Data written to bus (8-bits for 
viMoveOut8, 16-bits for 
viMoveOutl6, and 32-bits for 
viMoveOut32). 

length 

IN 

ViBusSize 

Number of elements to transfer, 
where the data width of the elements 
to transfer is 8-bits for viMoveOutS, 
16-bits for viMoveOutl6, or 32-bits 
for viMoveOut32. 

offset 

IN 

ViBusAddress 

Offset (in bytes) of the starting 
address or register to write to. 

space 

IN 

ViUIntl6 

Specifies the address space. (See the 
following table.) 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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viMoveOut8, viMoveOut16, and viMoveOut32 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid 
(due to attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN 

OFFSET 

The specified offset is not properly aligned for the 
access width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because 
the resource identified by vi has been locked for this 
kind of access. 


See Also viMoveln8, viMoveln16, viMoveln32, viOut8, viOut16, viOut32 
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viOpen 


Syntax 


Description 


Parameters 


viOpen 

viOpen (ViSession sesn , ViRsrc rsrcName , ViAccessMode 
accessMode, ViUInt32 timeout, ViSession vi) ; 

This function opens a session to the specified device. It returns a session 
identifier that can be used to call any other functions to that device. 


Name 

Direction 

Type 

Description 

accessMode 

IN 

ViAccessMode 

Specifies the modes by which the 
resource is to be accessed. The 
value vi exclusive lock is used 
to acquire an exclusive lock 
immediately upon opening a 
session. 




If a lock cannot be acquired, the 
session is closed and an error is 
returned. The vi load CONFIG 
value is used to configure attributes 
specified by some external 
configuration utility. If this value is 
not used, the session uses the 
default values provided by this 
specification. 




Multiple access modes can be used 
simultaneously by specifying a "bit¬ 
wise OR" of the values. (Must use 
vi null in VISA 1.0.) 

rsrcName 

IN 

ViRsrc 

Unique symbolic name of a 
resource. (See the following tables.) 

sesn 

IN 

ViSession 

Resource Manager session (should 
always be the Default Resource 
Manager for VISA returned from 
viOpenDef aultRM). 
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viOpen 


Name 

Direction 

Type 

Description 

timeout 

IN 

ViUInt32 

If the accessMode parameter 
requires a lock, this parameter 
specifies the absolute time period (in 
milliseconds) that the resource waits 
to get unlocked before this operation 
returns an error. Otherwise, this 
parameter is ignored. (Must use 
vi null in VISA 1.0.) 

vi 

OUT 

ViSession 

Unique logical identifier reference to 
a session. 


Address String Grammar for rsrcName Parameter 


Interface 

Syntax 

VXI 

vxi [board] : : VXI logical address [: : instr] 

VXI 

vxi [board] : :MEMACC 

VXI 

vxi [board] [:: VXI logical address] :: backplane 

GPIB-VXI 

GPIB-VXI [board] : : VXI logical address[: : INSTR] 

GPIB-VXI 

gpib-vxi [board] : :MEMACC 

GPIB-VXI 

gpib-vxi [board] [:: VXI logical address] : : backplane 

GPIB 

gpib [board] : : primary address [: : secondary address] [: : instr] 

GPIB 

gpib [board] : :INTFC 

ASRL 

asrl [board] [: : instr] 

TCPIP 

tcpip [board] : -.host address]: -.LAN device name] : : instr 

TCPIP 

tcpip[ board] : -.host address: -.port: : socket 


Examples of Address Strings for rsrcName Parameter 


Address String 

Description 

VXI0::1:: INSTR 

A VXI device at logical address 1 in VXI interface 
VXIO. 

GPIB-VXI::9::INSTR 

A VXI device at logical address 9 in a GPIB-VXI 
controlled VXI system. 
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viOpen 


GPIB::1::0::INS TR 

A GPIB device at primary address 1 and 
secondary address 0 in GPIB interface 0. 

ASRL1 ::INSTR 

A serial device located on port 1. 

VXI::MEMACC 

Board-level register access to the VXI interface. 

GPIB- VX11 ::MEMA C C 

Board-level register access to GPIB-VXI interface 
number 1. 

GPIB2::INTFC 

Interface or raw resource for GPIB interface 2. 

VXI::1 -BACKPLANE 

Mainframe resource for chassis 1 on the default 

VXI system, which is interface 0. 

TCPIPO:: 1.2.3.4::999:: 
SOCKET 

Raw TCPIP access to port 999 at the specified 
address. 

TCPIP::devicename@ 
company. com::INSTR 

TCPIP device using VXI-11 located at the specified 
address. This uses the default LAN Device Name 
of instO. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI_SUCCESS 

Session opened successfully. 

VI SUCCESS DEV NPRESENT 

Session Opened Successfully, but the device at 
the specified address is not responding. 

VI WARN CONFIG NLOADED 

The specified configuration either does not exist 
or could not be loaded using VISA-specified 
defaults. 
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viOpen 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

Insufficient system resources to open a 
session. 

VI ERROR INTF NUM NCONFIG 

The interface type is valid but the specified 
interface number is not configured. 

VI ERROR INV ACC MODE 

Invalid access mode. 

VI ERROR INV RSRC NAME 

Invalid resource reference specified. Parsing 
error. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR LIBRARY NFOUND 

A code library required by VISA could not be 
located or loaded. 

VI ERROR NSUP OPER 

The given sesn does not support this 
function. For VISA, this function is supported 
only by the Default Resource Manager 
session. 

VI ERROR RSRC BUSY 

The resource is valid but VISA cannot 
currently access it. 

VI ERROR RSRC LOCKED 

Specified type of lock cannot be obtained 
because the resource is already locked with 
a lock type incompatible with the lock 
requested. 

VI ERROR RSRC NFOUND 

Insufficient location information or resource 
not present in the system. 

VI ERROR TMO 

A session to the resource could not be 
obtained within the specified timeout period. 


viClose 
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viOpenDefaultRM 


Syntax 

Description 


Parameters 

Return Values 


viOpenDefaultRM 

viOpenDefaultRM(ViSession sesn) ; 


This function returns a session to the Default Resource Manager resource. 
This function must be called before any VISA functions can be invoked. The 
first call to this function initializes the VISA system, including the Default 
Resource Manager resource, and also returns a session to that resource. 
Subsequent calls to this function return unique sessions to the same Default 
Resource Manager resource. 


NOTE 

All devices to be used must be connected and operational prior to the first 
VISA function call (viOpenDefaultRM). The system is configured only 
on the first viOpenDefaultRM per process. 

If viOpenDefaultRM is first called without devices connected and then 
called again when devices are connected, the devices will not be 
recognized. You must close ALL Resource Manager sessions and 
reopen with all devices connected and operational. 


Name 

Direction 

Type 

Description 

sesn 

OUT 

ViSession 

Unique logical identifier to a Default Resource 
Manager session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Session to the Default Resource Manager resource 
created successfully. 
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viOpenDefaultRM 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

Insufficient system resources to create a session 
to the Default Resource Manager resource. 

VI ERROR INV SETUP 

Some implementation-specific configuration file is 
corrupt or does not exist. 

VI ERROR SYSTEM ERROR 

The VISA system failed to initialize. 


viOpen, viFindRsrc, viClose 
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viOut8, viOut16, and viOut32 


Syntax 


Description 


viOut8, viOut16, and viOut32 

viOut8 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUInt8 val8) ; 

viOutl6 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUIntl6 vail6) ; 

viOut32 (ViSession vi , ViUIntl6 space, ViBusAddress offset, 
ViUInt32 va!32) ; 


This function writes an 8-bit, 16-bit, or 32-bit word to the specified memory 
space (assigned memory base + offset). This function takes the 8-bit, 16-bit, 
or 32-bit value and stores its contents to the address space pointed to by 
space. The offset must be a valid memory address in the space. This 
function does not require viMapAddress to be called prior to its invocation. 

If the viSession parameter (vi) refers to an INSTR session, the offset 
parameter specifies a relative offset from the start of the instrument’s 
address space. If the viSession parameter (vi) refers to a MEMACC 
session, the offset parameter is an absolute offset from the start of memory 
in that VXI address space. The valid entries for specifying address space 
are: 


Value 

Description 

VI A16 SPACE 

Address the A16 address space of VXI/MXI bus. 

VI A24 SPACE 

Address the A24 address space of VXI/MXI bus. 

VI A32 SPACE 

Address the A32 address space of VXI/MXI bus. 


The high-level operations viOut8, viOutl6, and viOut32 operate 
successfully independently from the low-level operations (viMapAddress, 
viPeek8, viPeekl6, viPeek32, viPoke8, viPokel6, and 
viPoke32). The high-level and low-level operations should operate 
independently regardless of the configured state of the hardware that is 
used to perform memory accesses. 

For an INSTR resource, the offset is a relative address of the device 
associated with the given INSTR resource. For a MEMACC resource, the 
offset parameter specifies an absolute address. 
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viOut8, viOut16, and viOut32 


The offset specified in the viOut8, viOutl6, and viOut32 operations for 
an INSTR resource is the offset address relative to the device's allocated 
address base for the corresponding address space specified. 

For example, if space specifies vi_a16_space, offset specifies the offset 
from the logical address base address of the VXI device specified. If space 
specifies vi_a24_space or vi_a32_space, offset specifies the offset 
from the base address of the VXI device's memory space allocated by the 
VXI Resource Manager within VXI A24 or A32 space. 


Parameters 


Name 

Direction 

Type 

Description 

offset 

IN 

ViBusAddress 

Offset (in bytes) of the address or 
register to write to. 

space 

IN 

ViUIntl6 

Specifies the address space. (See the 
following table.) 

val8, 
vail 6, 
or val32 

IN 

ViUInt8, 
ViUIntl6, or 
ViUInt32 

Data to write to bus (8-bits for viOut8, 
16-bits for viOutl6, and 32-bits for 
viOut32). 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid 
(due to attributes being set to an inconsistent state). 
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viOut8, viOut16, and viOut32 


See Also 


Error Codes 

Description 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN 

OFFSET 

The specified offset is not properly aligned for the 
access width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


viln8, vilnl6, viln32, viPoke8, viPoke16, viPoke32, viMoveOut8, viMoveOut16, 
viMoveOut32 
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Description 


Parameters 


VISA Language Reference 

viParseRsrc 


viParseRsrc 


viParseRsrc (ViSession sesn, ViRsrc rsrcName, 
VIUIntl6 intfType, VlUIntl6 intfNum) ; 


Parse a resource string to get the interface information. This operation 
parses a resource string to verify its validity. It should succeed for all strings 
returned by viFindRsrc and recognized by viOpen. This operation is 
useful if you want to know what interface a given resource descriptor would 
use without actually opening a session to it. 

The values returned in intfType and intfNum correspond to the attributes 
VI_ATTR_INTF_TYPE and vi_attr_intf_num. These values would be 
the same if a user opened that resource with viOpen and queried the 
attributes with viGetAttribute. 

If a VISA implementation recognizes aliases in viOpen, it also recognizes 
those same aliases in viParseRsrc. Calling viParseRsrc with 
"VXI::1 ::INSTR" will produce the same results as invoking it with 
"vxi::1::instr". 


NOTE 

A VISA implementation should not perform any I/O to the specified 
resource during this operation. The recommended implementation of 
viParseRsrc will return information determined solely from the 
resource string and any static configuration information (e.g., .INI files 
or the Registry). 


Name 

Direction 

Type 

Description 

intfNum 

OUT 

VIUIntl6 

Board number of the interface of the 
given resource string. 

intfType 

OUT 

VIUIntl6 

Interface type of the given resource 
string. 

rsrcName 

IN 

ViRsrc 

Unique symbolic name of a resource. 
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viParseRsrc 


Name 

Direction 

Type 

Description 

sesn 

IN 

ViSession 

Resource Manager session (should 
always be the Default Resource 
Manager for VISA returned from 
viOpenDefaultRM). 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Resource string is valid. 


Error Codes 

Description 

VI ERROR ALLOC 

Insufficient system resources to parse the 
string. 

VI ERROR INTF NUM 

NCONFIG 

The interface type is valid but the specified 
interface number is not configured. 

VI ERROR INV RSRC NAME 

Invalid resource reference specified. Parsing 
error. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR LIBRARY NFOUND 

A code library required by VISA could not be 
located or loaded. 

VI ERROR NSUP OPER 

The given sesn does not support this operation. 
For VISA, this operation is supported only by the 
Default Resource Manager session. 

VI ERROR RSRC NFOUND 

Insufficient location information or resource 
not present in the system. 


See Also 


viFindRsrc, viOpen 
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Description 

Parameters 


Return Values 
See Also 


VISA Language Reference 

viPeek8, viPeek16, and viPeek32 


viPeek8, viPeek16, and viPeek32 

viPeek8 (ViSession vi, ViAddr addr, ViUInt8 val8) ; 
viPeekl6 (ViSession vi, ViAddr addr, ViUIntl6 val16) ; 
viPeek32 (ViSession vi, ViAddr addr, ViUInt32 val32) ; 

This function reads an 8-bit, 16-bit, or 32-bit value from the address location 
specified in addr. The address must be a valid memory address in the 
current process mapped by a previous viMapAddress call. 


Name 

Direction 

Type 

Description 

addr 

IN 

ViAddr 

Specifies the source address to read the 
value. 

val8, 
vail6 , or 
val32 

OUT 

ViUInt8, 
ViUIntl6, 

or 

ViUInt32 

Data read from bus (8-bits for viPeekS, 
16-bits for viPeekl6, and 32-bits for 
viPeek32). 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


NOTE 

ViAddr is defined as a void *. To do pointer arithmetic, you must cast 
this to an appropriate type (Viuint8, ViUIntl6, or ViUlnt32). Then, 
be sure the offset is correct for the type of pointer you are using. For 
example, (Viuint8 *)addr + 4 points to the same location as 
(ViUIntl6 *)addr + 2. 


None. 


viPoke8, viPoke16, viPoke32, viMapAddress, viln8, vilnl6, viln32 
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viPoke8, viPoke16, and viPoke32 


Syntax 

Description 

Parameters 


Return Values 
See Also 


viPoke8, viPoke16, and viPoke32 

viPoke8 (ViSession vi, ViAddr addr, ViUInt8 val8) ; 
viPokel6 (ViSession vi, ViAddr addr, ViUIntl6 val16) ; 
viPoke32 (ViSession vi, ViAddr addr, ViUInt32 val32) ; 

This function takes an 8-bit, 16-bit, or 32-bit value and stores its content to 
the address pointed to by addr. The address must be a valid memory 
address in the current process mapped by a previous viMapAddress call. 


Name 

Direction 

Type 

Description 

addr 

IN 

ViAddr 

Specifies the destination address to 
store the value. 

val8, 
vail 6 or 
val32 

IN 

ViUInt8, 
ViUIntl6, 

or 

ViUInt32 

Data written to bus (8-bits for viPokeS, 
16-bits for viPokel6, and 32-bits for 
viPoke32). 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


NOTE 

ViAddr is defined as a void *. To do pointer arithmetic, you must cast 
this to an appropriate type (Viuint8, ViUlntl6, or ViUlnt32). Then, 
be sure the offset is correct for the type of pointer you are using. For 
example, (ViUlnt8 *)addr + 4 points to the same location as 
(ViUIntl6 *)addr + 2. 


None. 


viPeek8, viPeek16, viPeek32, viMapAddress, viOut8, viOut16, viOut32 


Chapter 7 


249 













Syntax 

Description 


VISA Language Reference 

viPrintf 


viPrintf 

viPrintf (ViSession vi, ViString writeFmt, argl, arg2,...) ; 


This function converts, formats, and sends the parameters argl, arg2, ... to 
the device as specified by the format string. Before sending the data, the 
function formats the arg characters in the parameter list as specified in the 
writeFmt string. You should not use the viWrite and viPrintf functions 
in the same session. 

VISA functions that take a variable number of parameters (e.g., viPrintf, 
viScanf , and viQueryf ) are not callable from Visual Basic. Use the 
corresponding viVPrintf, viVScanf , and viVQueryf functions instead. 

The writeFmt string can include regular character sequences, special 
formatting characters, and special format specifiers. The regular characters 
(including white spaces) are written to the device unchanged. The special 
characters consist of \ (backslash) followed by a character. The format 
specifier sequence consists of % (percent) followed by an optional modifier 
(flag), followed by a format code. 

Up to four arg parameters may be required to satisfy a % format conversion 
request. In the case where multiple args are required, they appear in the 
following order: 

- field width (* with %d, %f, or %s) if used 

- precision (* with %d, %f, or %s) if used 

- array_size (* with %b, %B, %y, %d, or %f) if used 

- value to convert 

This assumes that a * is provided for both the field width and the precision 
modifiers in a %s, %d, or %f. The third arg parameter is used to satisfy a 
",*" comma operator. The fourth arg parameter is the value to be converted 
itself. 


For ANSI C compatibility the following conversion codes are also supported 
for output codes. These codes are 'i,' 'o,' 'u,' 'n,' 'x,' 'X,' 'e,' ’E,’ ’g,' ’G,' and ’p.’ 
For further explanation of these conversion codes, see the ANSI C 
Standard. 
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viPrintf 


Special Formatting Characters 

Special formatting character sequences send special characters. The 
following table lists the special characters and describes what they send to 
the device. 


\n 

Sends the ASCII LF character. The END identifier will also be 
automatically sent. 

\r 

Sends an ASCII CR character. 

\t 

Sends an ASCII TAB character. 

\### 

Sends the ASCII character specified by the octal value. 

V 

Sends the ASCII double-quote (") character. 

\\ 

Sends a backslash (\) character. 


Format Specifiers 

The format specifiers convert the next parameter in the sequence according 
to the modifier and format code, after which the formatted data is written to 
the specified device. The format specifier has the following syntax: 

% [modifiers] format code 

where format code specifies which data type in which the argument is 
represented. The modifiers are optional codes that describe the target data. 
In the following tables, a d format code refers to all conversion codes of type 
integer (d, i, o, u, x, x), unless specified as %d only. Similarly, an 
f format code refers to all conversion codes of type float (f, e, E, g, G), 
unless specified as %f only. 

Every conversion command starts with the % character and ends with a 
conversion character ( format code). Between the % character and the format 
code, the modifiers in the following tables can appear in the sequence. 
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ANSI C Standard Modifiers 


Modifier 

Supported with 
Format Code 

Description 

An integer 
specifying 
field width. 

d, f, s 
format codes 

This specifies the minimum field width of the converted argument. 

If an argument is shorter than the field width, it will be padded on the 
left (or on the right if the - flag is present). An asterisk (*) may be 
present in lieu of a field width modifier, in which case an extra arg is 
used. This arg must be an integer representing the field width. 

Special case: For the @H, @Q, and @B flags, the field width includes 
the #H, #!, and #B strings, respectively. 

An integer 
specifying 
precision. 

d, f, s format 
codes 

The precision string consists of a string of decimal digits. A . 

(decimal point) must prefix the precision string. An asterisk (*) 
may be present in lieu of a precision modifier, in which case an 
extra arg is used. This arg must be an integer representing the 
precision of a numeric field. The precision string specifies the 
following: 

■ The minimum number of digits to appear for the @i, 

@h, @q, and @b flags and the i, o, u, x, and x 
format codes. 

■ The maximum number of digits after the decimal point 
in case of f format codes. 

■ Maximum numbers of characters for the string (s) 
specifier. 

■ Maximum significant digits for g format code. 

An argument 

length 

modifier. 

h, 1, L, 
z, and z are 
legal values. 

(z and z are 
not ANSI C 
standard 
flags.) 

h (d, b, B 
format codes) 

1 (d, f, b, B 
format codes) 

L (f format 
codes) 

z, Z (b, B 
format codes) 

The argument length modifiers specify one of the following: 

■ The h modifier promotes the argument to a short or 
unsigned short, depending on the format code type. 

■ The l modifier promotes the argument to a long or 
unsigned long. 

■ The l modifier promotes the argument to a long double 
parameter. 

■ The z modifier promotes the argument to an array of 
floats. 

■ The z modifier promotes the argument to an array of 
doubles. 
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Enhanced Modifiers to ANSI C Standards 


Modifier 

Supported with 
Format Code 

Description 

A comma (,) 
followed by an 
integer n, where n 
represents the 
array size. 

%d (plus variants) 
and %f only 

The corresponding argument is interpreted as a reference to 
the first element of an array of size n. The first n elements of 
this list are printed in the format specified by the format code. 

An asterisk (*) may be present after the , modifier, in which 
case an extra arg is used. This arg must be an integer 
representing the array size of the given type. 

@1 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined NR1 compatible number, 
which is an integer without any decimal point (e.g., 123). 

@2 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined NR2 compatible number. 

The NR2 number has at least one digit after the decimal point 
(e.g., 123.45). 

@3 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined NR3 compatible number. 

An NR3 number is a floating point number represented in an 
exponential form (e.g., 1.2345E-67). 

@H 

%d (plus variants) 
and%f only 

Converts to an IEEE 488.2 defined <HEXADECIMAL 

NUMERIC RESPONSE DATA>. The number is represented 
in a base of sixteen form. Only capital letters should represent 
numbers. The number is of the form #hXXX.., where XXX. is a 
hexadecimal number (e.g., #haf35b). 

@Q 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined <OCTAL NUMERIC 
RESPONSE DATA>. The number is represented in a base 
of eight form. The number is of the form #QYYY.., where YYY.. 
is an octal number (e.g., #Q71234). 

@B 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined <BINARY NUMERIC 
RESPONSE DATA>. The number is represented in a base 
two form. The number is of the form #BZZZ.., where ZZZ. is 
a binary number (e.g., #B011101001). 
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The following are the allowed format code characters. A format specifier 
sequence should include one and only one format code. 

Standard ANSI C Format Codes 

% Send the ASCII percent (%) character, 

c Argument type: A character to be sent, 

d Argument type: An integer. 


Modifier 

Interpretation 

Default 

functionality 

Print integer in NR1 format (integer without a decimal point). 

@2 or @3 

The integer is converted into a floating point number and 
output in the correct format. 

field width 

Minimum field width of the output number. Any of the six 
IEEE 488.2 modifiers can also be specified with field width. 

Length modifier 1 

arg is a long integer. 

Length modifier h 

arg is a short integer. 

, array size 

arg points to an array of integers (or long or short integers, 
depending on the length modifier) of size array size. The 
elements of this array are separated by array size - 1 
commas and output in the specified format. 

f 

Argument type: A floating point number. 

Modifier 

Interpretation 

Default 

functionality 

Print a floating point number in NR2 format (a number with 
at least one digit after the decimal point). 

@1 

Print an integer in NR1 format. The number is truncated. 

@3 

Print a floating point number in NR3 format (scientific 
notation). Precision can also be specified. 

field width 

Minimum field width of the output number. Any of the six 
IEEE 488.2 modifiers can also be specified with field width. 

Length modifier 1 

arg is a double float. 
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Modifier 

Interpretation 

Length modifier L 

arg is a long double. 

, array size 

arg points to an array of floats (or doubles or long doubles), 
depending on the length modifier) of size array size. The 
elements of this array are separated by array size - 1 
commas and output in the specified format. 


s Argument type: A reference to a NULL-terminated 

string that is sent to the device without change. 

Enhanced Format Codes 

b Argument type: A location of a block of data. 


Flag or 
Modifier 

Interpretation 

Default 

functionality 

The data block is sent as an IEEE 488.2 <DEFINITE LENGTH 
ARBITRARY BLOCK RESPONSE DATA>. A count (long 
integer) must appear as a flag that specifies the number of 
elements (by default, bytes) in the block. A field width or 
precision modifier is not allowed with this format code. 

* (asterisk) 

An asterisk may be present instead of the count. In such a case, 
two args are used, the first of which is a long integer specifying 
the count of the number of elements in the data block. The 
second arg is a reference to the data block. The size of an 
element is determined by the optional length modifier (see 
below), the default being byte width. 

Length 
modifier h 

The data block is assumed to be an array of unsigned short 
integers (16-bits). The count corresponds to the number of words 
rather than bytes. The data is swapped and padded into 
standard IEEE 488.2 (big endian) format if native computer 
representation is different. 

Length 
modifier 1 

The data block is assumed to be an array of unsigned long 
integers. The count corresponds to the number of longwords 
(32-bits). Each longword data is swapped and padded into 
standard IEEE 488.2 (big endian) format if native computer 
representation is different. 
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Flag or 
Modifier 

Interpretation 

Length 
modifier z 

The data block is assumed to be an array of floats. The count 
corresponds to the number of floating point numbers (32-bits). 
The numbers are represented in IEEE 754 (big endian) format if 
native computer representation is different. 

Length 
modifier Z 

The data block is assumed to be an array of doubles. The count 
corresponds to the number of double floats (64-bits). The 
numbers are represented in IEEE 754 (big endian) format if 
native computer representation is different. 

B 

Argument type: A location of a block of data. The 
functionality is similar to b, except the data block is 
sent as an IEEE 488.2 dNDEFINITE LENGTH 
ARBITRARY BLOCK RESPONSE DATA>. This 
format involves sending an ASCII LF character with 
the END indicator set after the last byte of the block. 

y 

Argument Type: A location of block binary data. 

Flag or Modifier 

Interpretation 

Default 

functionality 

The data block is sent as raw binary data. A count (long 
integer) must appear as a flag that specifies the number of 
elements (by default, bytes) in the block. A field width or 
precision modifier is not allowed with this format code. 

* (asterisk) 

An asterisk may be present instead of the count. In such a 
case, two args are used, the first of which is a long integer 
specifying the count of the number of elements in the data 
block. The second arg is a reference to the data block. The 
size of an element is determined by the optional length 
modifier (see below), the default being byte width. 

Length modifier 
h 

The data block is an array of unsigned short integers (16-bits). 
The count corresponds to the number of words rather than 
bytes. If the optional ! ol byte order modifier is present, the 
data is sent in little endian format. Otherwise, the data is sent 
in standard IEEE 488.2 format. Data will be byte swapped and 
padded as appropriate if native computer representation is 
different. 


256 


Chapter 7 












VISA Language Reference 

viPrintf 


Flag or Modifier 

Interpretation 

Length Modifier 

1 

The data block is an array of unsigned long integers (32 bits). 
The count corresponds to the number of longwords rather than 
bytes. If the optional ! ol byte order modifier is present, the 
data is sent in little endian format; otherwise, the data is sent in 
standard IEE 488.2 format. Data will be byte swapped and 
padded as appropriate if native computer representation is 
different. 

Byte order 
modifier ! ob 

Data is sent in standard IEE 488.2 (big endian) format. This is 
the default behavior if neither ! ob nor ! ol is present. 

Byte order 
modifier ! ol 

Data is sent in little endian format. 


Parameters 


Name 

Direction 

Type 

Description 

argl, arg2 

IN 

N/A 

Parameters format string is applied to. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

String describing the format for 
arguments. 


Return Values 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Parameters were successfully formatted. 
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See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both 
are the same value). 

VI ERROR 10 

Could not perform write function because of I/O error. 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because 
the resource identified by vi has been locked for this 
kind of access. 

VI ERROR TMO 

Timeout expired before write function completed. 


viVPrintf 
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Syntax 

Description 


Parameters 


viQueryf 

viQueryf (ViSession vi, ViString writeFmt, 

ViString readFmt, argl, arg2,...) ; 

This function performs a formatted write and read through a single operation 
invocation. This function provides a mechanism of "Send, then receive" 
typical to a command sequence from a commander device. In this manner, 
the response generated from the command can be read immediately. 

This function is a combination of the viPrintf and viScanf functions. 
The first n arguments corresponding to the first format string are formatted 
by using the writeFmt string and then sent to the device. The write buffer is 
flushed immediately after the write portion of the operation completes. After 
these actions, the response data is read from the device into the remaining 
parameters (starting from parameter n + 1) using the readFmt string. 

This function returns the same VISA status codes as viPrintf, viScanf, 
and viFlush. 

VISA functions that take a variable number of parameters (e.g., viPrintf, 
viScanf, and viQueryf) are not callable from Visual Basic. Use the 
corresponding viVPrintf, viVScanf and viVQueryf functions instead. 


Name 

Direction 

Type 

Description 

argl, arg2 

IN OUT 

N/A 

Parameters on which write and read format 
strings are applied. 

readFmt 

IN 

ViString 

ViString describing the format of the 
read arguments. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

ViString describing the format of the 
write arguments. 
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Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Successfully completed the Query operation. 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt or readFmt string 
is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform read/write operation because of 
I/O error. 

VI ERROR NSUP FMT 

The format specifier is not supported for current 
argument type. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout occurred before read/write operation 
completed. 


viPrintf, viScanf, viVQueryf 
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Syntax 

Description 


Parameters 


viRead 


viRead (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retCount) ; 


This function synchronously transfers data from a device. The data that is 
read is stored in the buffer represented by buf. This function returns only 
when the transfer terminates. Only one synchronous read function can 
occur at any one time. A viRead operation can complete successfully if 
one or more of the following conditions were met: 


■ END indicator received 

■ Termination character read 

■ Number of bytes read is equal to count 


It is possible to have one, two, or all three of these conditions satisfied at the 
same time. 


NOTE 

You must set specific attributes to make the read terminate under specific 
conditions. See Appendix B - VISA Resource Classes. 


Name 

Direction 

Type 

Description 

buf 

OUT 

ViBuf 

Represents the location of a buffer to 
receive data from device. 

count 

IN 

ViUInt32 

Number of bytes to be read. 

retCount 

OUT 

ViUInt32 

Represents the location of an integer that 
will be set to the number of bytes actually 
transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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Special Value for retCount Parameter 


Value 

Description 

VI NULL 

Do not return the number of bytes transferred. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI_SUCCESS 

The function completed successfully and the 
END indicator was received (for interfaces that 
have END indicators). 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 

VI SUCCESS TERM CHAR 

The specified termination character was read. 


Error Codes 

Description 

VI ERROR ASRL FRAMING 

A framing error occurred during transfer. 

VI ERROR ASRL OVERRUN 

An overrun error occurred during transfer. A 
character was not read from the hardware 
before the next character arrived. 

VI ERROR ASRL PARITY 

A parity error occurred during transfer. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has 
been lost. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start read function because setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is 
not currently the controller in charge. 
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See Also 


Error Codes 

Description 

VI ERROR NLISTENERS 

No Listeners condition is detected (both NRFD 
and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error 
occurred during transfer. 

VI ERROR RAW RD PROT 

VIOL 

Violation of raw read protocol occurred during 
transfer. 

VI ERROR RAW WR PROT 

VIOL 

Violation of raw write protocol occurred during 
transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by v/'has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


viWrite 
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Parameters 
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viReadAsync 

viReadAsync (ViSession vi, ViBuf buf, ViUInt32 count, 
Vi Job Id job Id) ; 


This function asynchronously transfers data from a device. The data that is 
read is stored in the buffer represented by buf. This function normally returns 
before the transfer terminates. An I/O Completion event is posted when the 
transfer is actually completed. 

This function returns jobld, which you can use either with viTerminate 
to abort the operation or with an I/O Completion event to identify which 
asynchronous read operation completed. 

Since an asynchronous I/O request could complete before the 
viReadAsync operation returns and the I/O completion event can be 
distinguished based on the job identifier, an application must be made aware 
of the job identifier before the first moment that the I/O completion event 
could possibly occur. 

Setting the output parameter jobld before the data transfer even begins 
ensures that an application can always match the jobld parameter with the 
vi_attr_job_id attribute of the I/O completion event. 

If you pass VI_NULL as the jobld parameter to the viReadAsync 
operation, no jobld will be returned. This option may be useful if only one 
asynchronous operation will be pending at a given time. The value vi_null 
is a reserved jobld and has a special meaning in viTerminate. 

If multiple jobs are queued at the same time on the same session, an 
application can use the jobld to distinguish the jobs, as they are unique 
within a session. 


Name 

Direction 

Type 

Description 

buf 

OUT 

ViBuf 

Represents the location of a buffer to receive 
data from the device. 

count 

IN 

ViUInt32 

Number of bytes to be read. 


264 


Chapter 7 











VISA Language Reference 

viReadAsync 


Name 

Direction 

Type 

Description 

jobld 

OUT 

ViJobld 

Represents the location of a variable that will 
be set to the job identifier of this asynchronous 
read operation. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special value for jobld Parameter 


Value 

Description 

VI NULL 

Do not return a job identifier. 


Return Values 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI_SUCCESS 

Asynchronous read operation successfully queued. 

VI SUCCESS SYNC 

Read operation performed synchronously. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR QUEUE ERROR 

Unable to queue read operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


See Also viRead, viTerminate, viWrite, viWriteAsync 
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Description 


Parameters 

Return Values 


VISA Language Reference 

viReadSTB 


viReadSTB 

viReadSTB (ViSession vi , ViUIntl6 status); 


Read a status byte of the service request. This operation reads a service 
request status from a service requester (the message-based device). For 
example, on the IEEE 488.2 interface, the message is read by polling 
devices. For other types of interfaces, a message is sent in response to a 
service request to retrieve status information. 

For a session to a Serial device or TCPIP socket, if vi_attr_io_prot is 
vi_prot_ 4882_s trs , the device is sent the string "*STB?\n" and then 
the device's status byte is read. Otherwise, this operation is not valid. If the 
status information is only one byte long, the most significant byte is returned 
with the zero value. If the service requester does not respond in the actual 
timeout period, vi_error_tmo is returned. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to the session. 

status 

OUT 

ViUIntl6 

Service request status byte. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 
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Error Codes 

Description 

VI ERROR CONN LOST 

The I/O connection for the given session has 
been lost. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start operation because setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR NCIC 

The interface associated with the given vi is 
not currently the controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both 
NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred 
during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred 
during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR SRQ NOCCURRED 

Service request has not been received for 
the session. 

VI ERROR TMO 

Timeout expired before function completed. 
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viReadToFile 

viReadToFile (ViSession vi, ViConstString fileName, 
ViUInt32 count, ViUInt32 retCount) ; 


Read data synchronously and store the transferred data in a file. This read 
operation synchronously transfers data. The file specified in fileName is 
opened in binary write-only mode. 

If the value of vi_attr_file_append_en is vi_false, any existing 
contents are destroyed. Otherwise, the file contents are preserved. The data 
read is written to the file. This operation returns only when the transfer 
terminates. This operation is useful for storing raw data to be processed 
later. 

VISA uses ANSI C file operations. The mode used by viReadToFile is 
"wb" or "ab" depending on the value of vi_attr_file_append_en. 


Name 

Direction 

Type 

Description 

count 

IN 

ViUInt32 

Number of bytes to be read. 

fileName 

IN 

ViConstString 

Name of file to which data will be 
written. 

retCount 

OUT 

ViUInt32 

Number of bytes actually transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Value for retCount Parameter 


Completion Code 

Description 

VI NULL 

Do not return the number of bytes transferred. 
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Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

The function completed successfully and the 
END indicator was received (for interfaces that 
have END indicators). 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 

VI SUCCESS TERM CHAR 

The specified termination character was read. 


Error Codes 

Description 

VI ERROR ASRL FRAMING 

A framing error occurred during transfer. 

VI ERROR ASRL OVERRUN 

An overrun error occurred during transfer. A 
character was not read from the hardware 
before the next character arrived. 

VI ERROR ASRL PARITY 

A parity error occurred during transfer. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has 
been lost. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the 
specified file. Possible reasons include an 
invalid path or lack of access rights. 

VI ERROR FILE 10 

An error occurred while accessing the 
specified file. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR INV SETUP 

Unable to start read function because setup is 
invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is 
not currently the controller in charge. 
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See Also 


Error Codes 

Description 

VI ERROR NLISTENERS 

No Listeners condition is detected (both NRFD 
and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error 
occurred during transfer. 

VI ERROR RAW RD PROT 

VIOL 

Violation of raw read protocol occurred during 
transfer. 

VI ERROR RAW WR PROT 

VIOL 

Violation of raw write protocol occurred during 
transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


viRead, viWriteFromFile 
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Syntax 

Description 


viScanf 

viScanf (ViSession vi, ViString readFmt, argl, arg2,...) ; 


This operation receives data from a device, formats it by using the format 
string, and stores the data in the arg parameter list. The format string can 
have format specifier sequences, white space characters, and ordinary 
characters. 

VISA functions that take a variable number of parameters (e.g., viPrintf, 
viScanf, and viQueryf ) are not callable from Visual Basic. Use the 
corresponding viVPrintf, viVScanf , and viVQueryf functions instead. 

The white characters (blank, vertical tabs, horizontal tabs, form feeds, new 
line/linefeed, and carriage return) are ignored except in the case of %c and 
% []. All other ordinary characters except % should match the next character 
read from the device. 

A format specifier sequence consists of a %, followed by optional modifier 
flags, followed by one of the format codes , in that sequence. It is of the form: 

% [modifier] format code 

where the optional modifier describes the data format, while format code 
indicates the nature of data (data type). One and only one format code 
should be performed at the specifier sequence. A format specification 
directs the conversion to the next input arg. 

The results of the conversion are placed in the variable that the 
corresponding argument points to, unless the asterisk (*) assignment¬ 
suppressing character is given. In such a case, no arg is used and the 
results are ignored. 

The viScanf function accepts input until an END indicator is read or all 
the format specifiers in the readFmt string are satisfied. It also terminates 
if the format string character does not match the incoming character. Thus, 
detecting an END indicator before the readFmt string is fully consumed will 
result in ignoring the rest of the format string. 

Also, if some data remains in the buffer after all format specifiers in the 
readFmt string are satisfied, the data will be kept in the buffer and will be 
used by the next viScanf function. 
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There is a one-to-one correspondence between % format conversions and 
arg parameters in formatted I/O read operations except: 

■ If a * is present, no arg parameters are used. 

■ If a # is present instead of field width, two arg parameters are used. 
The first arg is a reference to an integer (%c, %s, %t, %T). This arg 
defines the maximum size of the string being read. The second arg 
points to the buffer that will store the read data. 

■ If a # is present instead of array_size, two arg parameters are used. 
The first arg is a reference to an integer (%d, %f) or a reference to a 
long integer (%b, %y). This arg defines the number of elements in 
the array. The second arg points to the array that will store the read 
data. 

If a size is present in field width for the %s, %t, and %T format conversions in 
formatted I/O read operations either as an integer or a # with a 
corresponding arg, the size defines the maximum number of characters to 
be stored in the resulting string. 

For ANSI C compatibility the following conversion codes are also supported 
for input codes. These codes are 'i,' 'o,' 'u,' 'n,' 'x,' 'X,' 'e,' 'E,' 'g,' 'G,' 'p,''[...],' 
and For further explanation of these conversion codes, see the ANSI 
C Standard. 

If viScanf times out, the read buffer is cleared before viScanf returns. 
When viScanf times out, the next call to viScanf will read from an empty 
buffer and force a read from the device. The following tables describe 
optional modifiers that can be used in a format specifier sequence. 
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ANSI C Standard Modifiers 


Modifier 

Supported with 
Format Codes 

Description 

An integer 
representing 
the field width 

%s, %c, %[ ] 
format codes 

It specifies the maximum field width that the argument will take. A # 
may also appear instead of the integer field width, in which case the 
next arg is a reference to the field width. This arg is a reference to 
an integer for %c and %s. The field width is not allowed for %d or %f . 

A length 
modifier (1, 
h, L, z or 
z). z and z are 
not ANSI C 
standard 
modifiers. 

h (d, b format 
codes) 

1 (d, f, b 
format codes) 

L (f format 
code) 

z , z (b format 
code) 

The argument length modifiers specify one of the following: 

■ The h modifier promotes the argument to be a 
reference to a short integer or unsigned short integer, 
depending on the format code. 

■ The l modifier promotes the argument to point to a 
long integer or unsigned long integer. 

■ The L modifier promotes the argument to point to a 
long double floating point parameter. 

■ The z modifier promotes the argument to point to an 
array of floats. 

■ The z modifier promotes the argument to point to an 
array of double floats. 

* (asterisk) 

All format codes 

An asterisk acts as the assignment suppression character. The 
input is not assigned to any parameters and is discarded. 


Enhanced Modifiers to ANSI C Standards 


Modifier 

Supported with 
Format Codes 

Description 

A comma (,) 
followed by an 
integer n, 
where n 
represents the 
array size. 

%d (plus 
variants) and 
%f only 

The corresponding argument is interpreted as a reference to the 
first element of an array of size n. The first n elements of this list are 
printed in the format specified by the conversion character. 

A number sign (#) may be present after the , modifier, in which 
case an extra arg is used. This arg must be an integer representing 
the array size of the given type. 

@1 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined NR1 compatible number, which 
is an integer without any decimal point (e.g., 123). 

@2 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined NR2 compatible number. The 
NR2 number has at least one digit after the decimal point (e.g., 
123.45). 
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Modifier 

Supported with 
Format Codes 

Description 

@H 

%d(plus variants) 
and %f only 

Converts to an IEEE 488.2 defined <HEXADECIMAL NUMERIC 
RESPONSE DATA>. The number is represented 
in a base of sixteen form. Only capital letters should represent 
numbers. The number is of the form #hXXX.., where XXX. is a 
hexadecimal number (e.g., #haf35b). 

@Q 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined <OCTAL NUMERIC 

RESPONSE DATA>. The number is represented in a base 
of eight form. The number is of the form #QYYY.., where YYY.. 
is an octal number (e.g., #Q71234). 

@B 

%d (plus variants) 
and %f only 

Converts to an IEEE 488.2 defined <BINARY NUMERIC 
RESPONSE DATA>. The number is represented in a base 
two form. The number is of the form #B ZZZ.., where ZZZ.. is 
a binary number (e.g., #B011101001). 


ANSI C Format Codes 


c Argument type: A reference to a character. White space in 

the device input stream is not ignored when using c. 


Flags or 
Modifiers 

Interpretation 

Default 

functionality 

A character is read from the device and stored in the 
parameter. 

field width 

field width number of characters are read and stored at the 
reference location (the default field width is 1). No NULL 
character is added at the end of the data block 

d 

Argument type: A reference to an integer. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

Characters are read from the device until an entire number is 
read. The number read must be in one of the following IEEE 
488.2 formats: <DECIMAL NUMERIC PROGRAM DATA", also 
known as NRf. Flexible numeric representation (NR1, NR2, 
NR3, ...). <NON-DECIMAL NUMERIC PROGRAM DATA> 

(#H , #Q, and #b). 
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Flags or 
Modifiers 

Interpretation 

field width 

The input number will be stored in a field at least this wide. 

Length modifier 

1 

arg is a reference to a long integer. 

Length modifier 

h 

arg is a reference to a short integer. Rounding is performed 
according to IEEE 488.2 rules (0.5 and up). 

, array size 

arg points to an array of integers (or long or short integers, 
depending on the length modifier) of size array size. The 
elements of this array should be separated by commas. 
Elements will be read until either array size number of 
elements are consumed or they are no longer separated 
by commas. 

f 

Argument type: A reference to a floating point number. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

Characters are read from the device until an entire number is 
read. The number read must be in either 

IEEE 488.2 formats: <DECIMAL NUMERIC PROGRAM 

DATA> (NRf), or <NON-DECIMAL NUMERIC PROGRAM 
DATA> (#H, #Q, and #B). 

field width 

The input number will be stored in a field at least this wide. 

Length modifier 

1 

arg is a reference to a double floating point number. 

Length modifier 

L 

arg is a reference to a long double number. 

, array size 

arg points to an array of floats (or doubles or long doubles, 
depending on the length modifier) of size array size. The 
elements of this array should be separated by commas. 
Elements will be read until either array size number of 
elements are consumed or they are no longer separated by 
commas. 
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s 

Argument type: A reference to a string. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

All leading white space characters are ignored. Characters 
are read from the device into the string until a white space 
character is read. 

field width 

This flag gives the maximum string size. If the field width 
contains a # sign, two arguments are used. The first argument 
read gives the maximum string size. The second should be a 
reference to a string. 

In the case of field width characters already read before 
encountering a white space, additional characters are read 
and discarded until a white space character is found. In the 
case of # field width, the actual number of characters read are 
stored back in the integer pointed to by the first argument. 


Enhanced Format Codes 


b 

Argument type: A reference to a data array. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

The data must be in IEEE 488.2 ARBITRARY BLOCK 
PROGRAM DATA> format. The format specifier sequence 
should have a flag describing the array size, which will give a 
maximum count of the number of bytes (or words or longwords, 
depending on length modifiers) to be read from the device. If 
the array size contains a # sign, two arguments are used. 

Default 

functionality 

(continued) 

The first argument read is a pointer to a long integer specifying 
the maximum number of elements that the array can hold. The 
second one should be a reference to an array. Also in this case, 
the actual number of elements read is stored back in the first 
argument. In absence of length modifiers, the data is assumed 
to be of byte-size elements. In some cases, data might be read 
until an END indicator is read. 
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Flags or 
Modifiers 

Interpretation 

Length modifier 
h 

The array is assumed to be an array of 16-bit words, and count 
refers to the number of words. The data read from the interface 
is assumed to be in IEEE 488.2 (big endian) byte ordering. It 
will be byte swapped and padded as appropriate to the native 
computer format. 

Length modifier 

1 

The array is assumed to be a block of 32-bit longwords rather 
than bytes, and count refers to the number of longwords. The 
data read from the interface is assumed to be in IEEE 488.2 
(big endian) byte ordering. It will be byte swapped and padded 
as appropriate to the native computer format. 

Length modifier 

z 

The data block is assumed to be a reference to an array of 
floats, and count refers to the number of floating point numbers. 
The data block received from the device is an array of 32-bit 
IEEE 754 format floating point numbers. 

Length modifier 
z 

The data block is assumed to be a reference to an array of 
doubles, and the count refers to the number of floating point 
numbers. The data block received from the device is an array 
of 64-bit IEEE 754 format floating point numbers. 

t 

Argument type: A reference to a string. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

Characters are read from the device until the first END indicator 
is received. The character on which the END indicator was 
received is included in the buffer. 

field width 

This flag gives the maximum string size. If an END indicator is 
not received before field width number of characters, additional 
characters are read and discarded until an END indicator 
arrives. Afield width has the same meaning as in %s. 
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T 

Argument type: A reference to a string. 

Flags or 
Modifiers 

Interpretation 

Default 

functionality 

Characters are read from the device until the first linefeed 
character (\n) is received. The linefeed character is included in 
the buffer. 

field width 

This flag gives the maximum string size. If a linefeed character 
is not received before field width number of characters, 
additional characters are read and discarded until a linefeed 
character arrives, afield width has the same meaning as in %s. 

y 

Argument Type: A location of block binary data. 

Flag or Modifier 

Interpretation 

Default 

functionality 

The data block is read as raw binary data. The format specifier 
sequence should have a flag describing the array size, which 
will give a maximum count of the number of bytes (or words or 
longwords, depending on length modifiers) to be read from the 
device. If the array size contains a # sign, two arguments are 
used. 

The first argument read is a pointer to a long integer specifying 
the maximum number of elements that the array can hold. The 
second argument should be a reference to an array. Also, in 
this case, the actual number of elements read is stored back in 
the first argument. In the absence of length modifiers, the data 
is assumed to be of byte-size elements. In some cases, data 
might be read until an END indicator is read. 

Length modifier 
h 

The data block is assumed to be a reference to an array of 
unsigned short integers (16-bits). The count corresponds to the 
number of words rather than bytes. If the optional !ol byte 
order modifier is present, the data being read is assumed to be 
in little endian format; otherwise, the data being read is 
assumed to be in standard IEE 488.2 format. Data will be byte 
swapped and padded as appropriate to native computer 
format. 
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Flags or 
Modifiers 

Interpretation 

Length Modifier 

1 

The data block is assumed to be a reference to an array of 
unsigned long integers (32 bits). The count corresponds to the 
number of longwords rather than bytes. If the optional ! ol byte 
order modifier is present, the data being read is assumed to be 
in little endian format. Otherwise, the data being read is 
assumed to be in standard IEE 488.2 format. Data will be byte 
swapped and padded as appropriate if native computer 
representation is different. 

Byte order 
modifier !ob 

Data being read is assumed to be in standard IEE 488.2 (big 
endian) format. This is the default behavior if neither !ob nor 
! ol is present. 

Byte order 
modifier !ol 

Data being read is assumed to be in little endian format. 


Parameters 


Name 

Direction 

Type 

Description 

argl, 

arg2 

OUT 

N/A 

A list with the variable number of 
parameters into which the data is read and 
the format string is applied. 

readFmt 

IN 

ViString 

String describing the format for arguments. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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See Also 
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viScanf 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Data was successfully read and formatted into arg 
parameter(s). 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform read function because of I/O 
error. 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before read function completed. 


viVScanf 
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Syntax 

Description 


Parameters 


viSetAttribute 


viSetAttribute(ViSession/ViEvent/ViFindList vi, 
ViAttr attribute, ViAttrState attrState) ; 


This function sets the state of an attribute for the specified session. The 
viSetAttribute operation is used to modify the state of an attribute 
for the specified session, event, or find list. 

If a resource cannot set an optional attribute state and the specified attribute 
state is valid and the attribute description does not specify otherwise, 
viSetAttribute returns error code VI_ERROR_NSUP_ATTR_STATE. 

Both VI_WARN_NSUP_ATTR_STATE and VI_ERROR_NSUP_ATTR_STATE 
indicate that the specified attribute state is not supported. Unless a specific 
rule states otherwise, a resource normally returns the error code 
vi_error_nsup_attr_state when it cannot set a specified attribute 
state. The completion code vi_warn_nsup_attr_state is intended to 
alert the application that although the specified optional attribute state is 
not supported, the application should not fail. 

One example is attempting to set an attribute value that would increase 
performance speeds. This is different than attempting to set an attribute 
value that specifies required but nonexistent hardware (such as specifying a 
VXI ECL trigger line when no hardware support exists) or a value that would 
change assumptions a resource might make about the way data is stored or 
formatted (such as byte order). See specific attribute descriptions for text 
that allows the completion code vi_warn_nsup_attr_state. 


Name 

Direction 

Type 

Description 

attribute 

IN 

ViAttr 

Resource attribute for which the state 
is modified. 

attrState 

IN 

ViAttrState 

The state of the attribute to be set for 
the specified resource. The 
interpretation of the individual attribute 
value is defined by the resource. 
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Return Values 


See Also 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

ViEvent 

ViFindList 

Unique logical identifier to a session, 
event, or find list. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Attribute value set successfully. 

VI WARN NSUP ATTR STATE 

Although the specified attribute state is 
valid, it is not supported by this resource 
implementation. (The application will still 
work, but this may have a performance 
impact.) 


Error Codes 

Description 

VI ERROR ATTR READONLY 

The specified attribute is read-only. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP ATTR 

The specified attribute is not defined by the 
referenced resource. 

VI ERROR NSUP ATTR STATE 

The specified state of the attribute is not valid, 
or is not supported as defined by the 
resource. (The application probably will not 
work if this error is returned.) 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


viGetAttribute. See Appendix B - VISA Resource Classes for a list of 
attributes and attribute values. 
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Syntax 

Description 


Parameters 


viSetBuf 

viSetBuf (ViSession vi, ViUIntl6 mask, ViUInt32 size); 


Set the size for the formatted I/O and/or serial communication buffer(s). 
This operation changes the buffer size of the read and/or write buffer for 
formatted I/O and/or serial communication. The mask parameter specifies 
whichbuffer to set the size of. The mask parameter can specify multiple 
buffers by bit-ORing any of the following values together. 


Flag 

Interpretation 

VI READ BUF 

Formatted I/O read buffer. 

VI WRITE BUF 

Formatted I/O write buffer. 

VI 10 IN BUF 

I/O communication receive buffer. 

VI 10 OUT BUF 

I/O communication transmit buffer. 


For backward compatibility, vi_io_in_buf is the same as 
VI_ASRL_IN_BUF and VI_I0_0UT_BUF is the same as 
VI_ASRL_OUT_BUF. 

Since not all serial drivers support user-defined buffer sizes, it is possible 
that a specific implementation of VISA may not be able to control this 
feature. If an application requires a specific buffer size for performance 
reasons, but a specific implementation of VISA cannot guarantee that size, 
it is recommended to use some form of handshaking to prevent overflow 
conditions. 


Name 

Direction 

Type 

Description 

mask 

IN 

ViUIntl6 

Specifies the type of buffer. 

size 

IN 

ViUInt32 

The size to be set for the specified buffer(s). 

vi 

IN 

ViSession 

Unique logical identifier to a session. 
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Return Values 


See Also 
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viSetBuf 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Buffer size set successfully. 

VI WARN NSUP BUF 

The specified buffer is not supported. 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate the buffer(s) of 
the specified size because of insufficient system 
resources. 

VI ERROR INV MASK 

The system cannot set the buffer for the given 
mask. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


viFlush 
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Syntax 

Description 

Parameters 


Return Values 


viSPrintf 

viSPrintf (ViSession vi, ViBuf buf, 
ViString writeFmt, argl, arg2, ...) ; 


Same as viPrintf, except the data are written to a user-specified buffer 
rather than the device. This operation is similar to viPrintf, except that 
the output is not written to the device, but is written to the user-specified 
buffer. This output buffer will be NULL terminated. 

If the viSPrintf operations outputs an END indicator before all the 
arguments are satisfied, the rest of the writeFmt string will be ignored and 
the buffer string will still be terminated by a NULL. 


Name 

Direction 

Type 

Description 

argl, arg2 

IN 

N/A 

A list containing the variable number 
of parameters on which the format 
string is applied. The formatted data 
are written to the specified device. 

buf 

OUT 

ViBuf 

Buffer where data are to be written. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

The format string to apply to 
parameters in viVAList. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Parameters were successfully formatted. 
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viSPrintf 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient system resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


viPrintf 
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viSScanf 

Syntax viSScanf (ViSession vi, ViBuf buf, 

vistring readFmt, argl, arg2, ...); 

Description This operation receives data from a user-specified buffer, formats it by using 

the format string, and stores the data in the arg parameter list. The format 
string can have format specifier sequences, white space characters, and 
ordinary characters. This function is the same as viScanf , except data 
are read from a user-specified buffer instead of a device. 

Parameters 


Name 

Direction 

Type 

Description 

argl, arg2 

OUT 

N/A 

A list with the variable number of 
parameters into which the data are 
read and the format string is applied. 

buf 

IN 

ViBuf 

Buffer from which data are read and 
formatted. 

readFmt 

IN 

ViString 

The format string to apply to 
parameters in viVAList. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Data was successfully read and formatted into 
arg parameter(s). 
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Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient system resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 
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Syntax 

Description 

Parameters 


Return Values 


viStatusDesc 

viStatusDesc(ViSession/ViEvent/ViFindList vi, 
ViStatus status, ViString desc) ; 


This function returns a user-readable string that describes the status code 
passed to the function. If a status code cannot be interpreted by the session, 
ViStatusDesc returns the warning Vl_WARN_UNKNOWN_STATUS. 


Name 

Direction 

Type 

Description 

desc 

OUT 

ViString 

The user-readable string interpretation of 
the status code passed to the function. Must 
be at least 256 characters to receive output. 

status 

IN 

ViStatus 

Status code to interpret. 

vi 

IN 

ViSession 

ViEvent 

ViFindList 

Unique logical identifier to a session, event, 
or find list. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Description successfully returned. 

VI WARN UNKNOWN STATUS 

The status code passed to the function could 
not be interpreted. 
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Syntax 


Description 


Parameters 


Return Values 


VISA Language Reference 

viTerminate 


viTerminate 

viTerminate (ViSession vi, ViUIntl6 degree, 
ViJobld jobld) ; 


NOTE 

This function is not implemented in Agilent VISA since all I/O is done 
synchronously. 


This function requests a VISA session to terminate normal execution of an 
operation. This operation requests a session to terminate normal execution 
of an operation, as specified by the jobld parameter. The jobld parameter is 
a unique value generated from each call to an asynchronous operation. 

If a user passes VI_NULL as the jobld value to viTerminate, a VISA 
implementation should abort any calls in the current process executing on 
the specified vi. Any call that is terminated this way should return 
vi_error_abort. Due to the nature of multi-threaded systems, for 
example where operations in other threads may complete normally before 
the operation viTerminate has any effect, the specified return value is not 
guaranteed. 


Name 

Direction 

Type 

Description 

degree 

IN 

ViUIntl6 

VI NULL 

jobld 

IN 

ViJobld 

Specifies an operation identifier. 

vi 

IN 

ViSession 

Unique logical identifier to an object. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 
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viTerminate 


See Also 


Completion Code 

Description 

VI_SUCCESS 

Request serviced successfully. 


Error Codes 

Description 

VI ERROR ABORT 

Calls in the current process executing on the 
specified vi are aborted. 

VI ERROR INV DEGREE 

Invalid degree specified. 

VI ERROR INV JOB ID 

Invalid job identifier specified. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 


viReadAsync, viWriteAsync, viMoveAsync 
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Syntax 

Description 

Parameters 


VISA Language Reference 

villninstallHandler 


villninstallHandler 

viUninstallHandler (ViSession vi, ViEventType eventType, 
ViHndlr handler, ViAddr userHandle) ; 


This function allows applications to uninstall handlers for events on 
sessions. Applications should also specify the value in the userHandle 
parameter that was passed to vilnstallHandler while installing the 
handler. 

VISA identifies handlers uniquely using the handler reference and the 
userHandle. All the handlers, for which the handler reference and the 
userHandle matches, are uninstalled. 


Name 

Direction 

Type 

Description 

eventType 

IN 

ViEventType 

Logical event identifier. 

handler 

IN 

ViHndlr 

Interpreted as a valid reference to a 
handler to be uninstalled by an 
application. (See the following table.) 

userHandle 

IN 

ViAddr 

A value specified by an application 
that can be used for identifying 
handlers uniquely in a session for an 
event. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


The following events are valid: 


Event Name 

Description 

VI EVENT 10 COMPLETION 

Notification that an asynchronous operation has 
completed 

VI EVENT SERVICE REQ 

Notification that a device is requesting service. 

VI EVENT TRIG 

Notification that a hardware trigger was received 
from a device. 

VI EVENT VXI SIGP 

Notification that a VXI signal or VXI interrupt has 
been received from a device. 
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viUninstallHandler 


Return Values 


See Also 


Special Value for handler Parameter 


Value 

Action Description 

VI ANY HNDLR 

Uninstall all the handlers with the matching value in the 
UserHandle parameter. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Event handler successfully uninstalled. 


Error Codes 

Description 

VI ERROR HNDLR NINSTALLED 

A handler is not currently installed for the 
specified event. 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV HNDLR REF 

Either the specified handler reference or the 
user context value (or both) does not match 
any installed handler. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 


See the handler prototype viEventHandler for its parameter description. 
See the viEnableEvent description for information about enabling 
different event handling mechanisms. See individual event descriptions for 
context definitions. 
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Syntax 

Description 

Parameters 

Return Values 


See Also 


VISA Language Reference 

villnlock 


villnlock 

viUnlock (ViSession vi) ; 

This function is used to relinquish a lock previously obtained using the 
viLock function. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

The lock was successfully relinquished. 

VI SUCCESS NESTED 

EXCLUSIVE 

The call succeeded, but this session still has 
nested exclusive locks. 

VI SUCCESS NESTED 

SHARED 

The call succeeded, but this session still has 
nested shared locks. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given vi does not identify a valid session or 
object. 

VI ERROR SESN NLOCKED 

The current session did not have any lock on the 
resource. 


viLock. For more information on locking, see Chapter 4 - Programming 
with VISA. 
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Syntax 

Description 

Parameters 

Return Values 


See Also 


viUnmapAddress 

viUnmapAddress (ViSession vi) ; 

This function unmaps memory space previously mapped by the 
viMapAddress function. 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR WINDOW NMAPPED 

The specified session is not currently mapped. 


viMapAddress 
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Syntax 

Description 

Parameters 


VISA Language Reference 

villnmapTrigger 


viUnmapTrigger 

viUnmapTrigger(ViSession vi, Vilntl6 trigSrc, 
Vi Inti 6 trigDest) ; 


This operation can be used to map one trigger line to another. This operation 
is valid only on VXI Backplane (BACKPLANE) sessions. 

This operation unmaps only one trigger mapping per call. If viMapTrigger 
was called multiple times on the same BACKPLANE resource and created 
multiple mappings for either trigSrc or trigDest, trigger mappings other than 
the one specified by trigSrc and trigDest remain in effect after this call 
completes. 


Name 

Direction 

Type 

Description 

trigDest 

IN 

Vilntl6 

Destination line used in previous 
map. 

trigSrc 

IN 

Vilntl6 

Source line used in previous map. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 


Special Value for trgSrc Parameter 


Value 

Action Description 

VI TRIG ECLO - VI TRIG ECL1 

Unmap the specified VXI ECL trigger line. 

VI TRIG PANEL IN 

Unmap the controller's front panel trigger 
input line. 

VI TRIG PANEL OUT 

Unmap the controller's front panel trigger 
output line. 

VI TRIG TTLO - VI TRIG TTL7 

Unmap the specified VXI TTL trigger line. 
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VISA Language Reference 

viUnmapTrigger 


Special Values for trigDest Parameter 


Value 

Action Description 

VI TRIG ALL 

Unmap all trigger lines to which trigSrc is 
currently connected. 

VI TRIG ECLO - VI TRIG ECL1 

Unmap the specified VXI ECL trigger line. 

VI TRIG PANEL IN 

Unmap the controller's front panel trigger 
input line. 

VI TRIG PANEL OUT 

Unmap the controller's front panel trigger 
output line. 

VI TRIG TTLO - VI TRIG TTL7 

Unmap the specified VXI TTL trigger line. 


Return Values 


Type ViStatus This is the function return status. It returns either a 

completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR INV LINE 

One of the specified lines (trigSrc or trigDest) is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP LINE 

One of the specified lines (trigSrc or trigDest) is 
not supported by this VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TRIG NMAPPED 

The path from trigSrc to trigDest is not currently 
mapped. 


See Also BACKPLANE Resource Description 
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Syntax 

Description 

Parameters 


Return Values 


VISA Language Reference 

viVPrintf 


viVPrintf 

viVPrintf (ViSession vi, ViString writeFmt, 
ViVAList pa rams) ; 


This function converts, formats, and sends params to the device as specified 
by the format string. This function is similar to viPrintf , except that the 
ViVAList parameters list provides the parameters rather than separate 
arg parameters. 


Name 

Direction 

Type 

Description 

params 

IN 

ViVAList 

A list containing the variable number of 
parameters on which the format string is 
applied. The formatted data is written to 
the specified device. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

The format string to apply to parameters 
in ViVAList. See viPrintf for 
description. 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Parameters were successfully formatted. 
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VISA Language Reference 

viVPrintf 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform write function because of I/O 
error. 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before write function completed. 


viPrintf 
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Syntax 

Description 


Parameters 


VISA Language Reference 

viVQueryf 


viVQueryf 

viVQueryf (ViSession vi, ViString writeFmt, ViString 
readFmt,v iVAList params) ; 


This function performs a formatted write and read through a single operation 
invocation. This function is similar to viQueryf , except that the viVAList 
parameters list provides the parameters rather than the separate arg 
parameter list in viQueryf. 


NOTE 

VISA functions that take a variable number of parameters (e.g., 
viPrintf, viScanf, and viQueryf) are not callable from Visual Basic. 
Use the corresponding viVPrintf, viVScanf, and viVQueryf 
functions instead. 


Name 

Direction 

Type 

Description 

params 

IN OUT 

ViVAList 

A list containing the variable number of write 
and read parameters. The write parameters 
are formatted and written to the specified 
device. The read parameters store the data 
read from the device after the format string 
is applied to the data. 

readFmt 

IN 

ViString 

The format string is applied to read 
parameters in ViVAList. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

The format string is applied to write 
parameters in ViVAList. 
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Return Values 


See Also 


VISA Language Reference 

viVQueryf 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Successfully completed the Query operation. 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt or readFmt string 
is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform read/write operation because of 
I/O error. 

VI ERROR NSUP FMT 

The format specifier is not supported for current 
argument type. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because 
the resource identified by vi has been locked for this 
kind of access. 

VI ERROR TMO 

Timeout occurred before read/write operation 
completed. 


viVPrintf, viVScanf, viQueryf 
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Syntax 

Description 

Parameters 


Return Values 


VISA Language Reference 

viVScanf 


viVScanf 

viVScanf (ViSession vi, ViString readFmt, ViVAList params) ; 


This function reads, converts, and formats data using the format specifier 
and then stores the formatted data in params. This function is similar to 
viScanf , except that the ViVAList parameters list provides the 
parameters rather than separate arg parameters. 


Name 

Direction 

Type 

Description 

params 

OUT 

ViVAList 

A list with the variable number of 
parameters into which the data is read 
and the format string is applied. 

readFmt 

IN 

ViString 

The format string to apply to parameters 
in ViVAList. See viScanf for description. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Data was successfully read and formatted into arg 
parameter(s). 
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VISA Language Reference 

viVScanf 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR 10 

Could not perform read function because of I/O 
error. 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not 
supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before read function completed. 


viScanf 
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viVSPrintf 


viVSPrintf 

Syntax viVSPrintf (ViSession Vi, ViBuf buf, ViString writeFmt, 

viVAList pa rams) ; 

Description Same as viVPrintf , except data are written to a user-specified buffer 

rather than a device. This operation is similar to viVPrintf, except the 
output is not written to the device but is written to the user-specified buffer. 
This output buffer will be NULL terminated. 

If the viVSPrintf operation outputs an END indicator before all the 
arguments are satisfied, the rest of the writeFmt string will be ignored and 
the buffer string will still be terminated by a NULL. 

Parameters 


Name 

Direction 

Type 

Description 

buf 

OUT 

ViBuf 

Buffer where data are to be written. 

params 

IN 

ViVAList 

A list containing the variable number of 
parameters on which the format string is 
applied. The formatted data are written to 
the specified device. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

writeFmt 

IN 

ViString 

The format string to apply to parameters 
in ViVAList. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Parameters were successfully formatted. 
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VISA Language Reference 

viVSPrintf 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is 
not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


viSPrintf, viVPrintf 
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viVSScanf 


viVSScanf 

Syntax viVSScanf (ViSession Vi, ViBuf buf, ViString readFmt, 

viVAList pa rams) ; 

Description This function reads, converts, and formats data using the format specifier 

and then stores the formatted data in params. This operation is similar to 
viVScanf , except data are read from a user-specified buffer rather than a 
device. 

Parameters 


Name 

Direction 

Type 

Description 

buf 

IN 

ViBuf 

Buffer from which data are read and 
formatted. 

params 

OUT 

ViVAList 

A list with the variable number of 
parameters into which data are read and 
the format string is applied. 

readFmt 

IN 

ViString 

The format string to apply to parameters 
in ViVAList. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Return Values 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Data were successfully read and formatted 
into arg parameter(s). 
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VISA Language Reference 

viVSScanf 


See Also 


Error Codes 

Description 

VI ERROR ALLOC 

The system could not allocate a formatted I/O 
buffer because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is 
invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is 
not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 


viSScanf, viVScanf 
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Syntax 

Description 


Parameters 


VISA Language Reference 

viVxiCommandQuery 


viVxiCommandQuery 

viVxiCommandQuery(ViSession vi, ViUIntl6 mode, 
ViUInt32 cmd, ViUInt32 response) ; 


Send the device a miscellaneous command or query and/or retrieve the 
response to a previous query. This operation can send a command or query 
or receive a response to a query previously sent to the device. The mode 
parameter specifies whether to issue a command and/or retrieve a 
response, and what type or size of command and/or response to use. 

If the mode parameter specifies sending a 16-bit command, the upper half of 
the cmd parameter is ignored. If the mode parameter specifies just retrieving 
a response, the cmd parameter is ignored. If the mode parameter specifies 
sending a command only, the response parameter is ignored and may be 
vi_null. If a response is retrieved but is only a 16-bit value, the upper half 
of the response parameter will be set to 0. 

Refer to the VXI Specification for defined word serial commands. The 
command values Byte Available, Byte Request, Clear, and 
Trigger are not valid for this operation. 


Name 

Direction 

Type 

Description 

cmd 

IN 

ViUInt32 

The miscellaneous command to send. 

mode 

IN 

ViBuf 

Specifies whether to issue a command 
and/or retrieve a response. See the 
Description section for actual values. 

response 

OUT 

ViUInt32 

The response retrieved from the device. 

If the mode specifies sending a command, 
this parameter may be vi null. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


308 


Chapter 7 













VISA Language Reference 

viVxiCommandQuery 


Special Values for mode Parameter 


Mode 

Action Description 

VI VXI CMD16 

Send 16-bit Word Serial command. 

VI VXI CMD16 RESPI6 

Send 16-bit Word Serial query, get 16-bit response. 

VI VXI CMD32 * 

Send 32-bit Word Serial command. 

VI VXI CMD32 RESPI6* 

Send 32-bit Word Serial query, get 16-bit response. 

VI VXI CMD32 RESP32* 

Send 32-bit Word Serial query, get 32-bit response. 

VI VXI RESPI6* 

Get 16-bit response from previous query. 

VI VXI RESP32* 

Get 32-bit response from previous query. 


* Not supported in Agilent VISA 


Return Values 


Type viStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI_SUCCESS 

Operation completed successfully. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error 
occurred during transfer. 

VI ERROR INV MODE 

The value specified by the mode parameter 
is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error 
occurred during transfer. 
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VISA Language Reference 

viVxiCommandQuery 


See Also 


Error Codes 

Description 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred 
during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred 
during transfer. 

VI ERROR RESP PENDING 

A previous response is still pending, causing 
a multiple query error. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


INSTR Resource Description 


310 


Chapter 7 










VISA Language Reference 

viWaitOnEvent 


Syntax 


Description 


viWaitOnEvent 

viWaitOnEvent (ViSession vi, ViEventType inEventType, 
ViUInt32 timeout, ViEventType outEventType, 

ViEvent outContext) ; 


This function waits for an occurrence of the specified event for a given 
session. In particular, this function suspends execution of an application 
thread and waits for an event inEventType for at least the time period 
specified by timeout. See the individual event descriptions for context 
definitions. 

If the specified inEventType is vi_all_enabled_events, the function 
waits for any event that is enabled for the given session. If the specified 
timeout value is vi_tmo_infinite, the function is suspended indefinitely 
to wait for an occurrence of an event. 

If the value vi_tmo_immediate is specified in the timeout parameter of 
viWaitOnEvent, application execution is not suspended. This operation 
can be used to dequeue events from an event queue by setting the timeout 
value to VI_TMO_IMMED I ATE. 

viWaitOnEvent removes the specified event from the event queue if one 
that matches the type is available. The process of dequeuing makes an 
additional space available in the queue for events of the same type. 

You must call viEnableEvent to enable the reception of events of the 
specified type before calling viWaitOnEvent. viWaitOnEvent does not 
perform any enabling or disabling of event reception. 

If the value vi_null is specified in the outContext parameter of 
viWaitOnEvent and the return value is successful, viClose is 
automatically invoked on the event context rather than returning it to the 
application. 

The outEventType and outContext parameters to the viWaitOnEvent 
operation are optional. They can be used if the event type is known from the 
inEventType parameter or if the eventContext is not needed to retrieve 
additional information. 
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viWaitOnEvent 


NOTE 

Since system resources are used when waiting for events 
(viWaitOnEvent), the viClose function must be called to free up 
event contexts (outContext). 


This table lists events and associated read-only attributes implemented by 
Agilent VISA that can be read to get event information on a specific event. 
Use the viReadSTB function to read the status byte of the service request 

Instrument Control (INSTR) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT SERVICE 

REQUEST 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT SERVICE 

REQ 

VI EVENT VXI SIGP 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI STOP 


VI ATTR SIGP STATUS ID 

ViUIntl6 

OtoFFFFh 

VI EVENT TRIG 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIG 


VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 
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VISA Language Reference 

viWaitOnEvent 


Memory Access (MEMACC) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 


GPIB Bus Interface (INTFC) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT GPIB CIC 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB CIC 


VI ATTR GPIB RECV CIC 

STATE 

ViBoolean 

VI TRUE 

VI FALSE 

VI EVENT GPIB TALK 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB TALK 

VI EVENT GPIB 

LISTEN 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT GPIB 

LISTEN 

VI EVENT CLEAR 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT CLEAR 

VI EVENT TRIGGER 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIGGER 


VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG SW 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 
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viWaitOnEvent 


VXI Mainframe Backplane (BACKPLANE) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT TRIG 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG ID 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

VI EVENT VXI VME 

SYSFAIL 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI VME 

SYSFAIL 

VI EVENT VXI VME 

SYSRESET 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT VXI VME 

SYSRESET 


TCPIP Socket (SOCKET) Resource Events 


Event Name 

Attributes 

Data Type 

Range 

VI EVENT 10 

COMPLETION 

VI ATTR EVENT TYPE 

ViEventType 

VI EVENT 10 

COMPLETION 


VI ATTR STATUS 

ViStatus 

N/A 


VI ATTR JOB ID 

ViJobld 

N/A 


VI ATTR BUFFER 

ViBuf 

N/A 


VI ATTR RET COUNT 

ViUInt32 

0 to FFFFFFFFh 


VI ATTR OPER NAME 

ViString 

N/A 


Parameters 


Name 

Direction 

Type 

Description 

inEventType 

IN 

ViEventType 

Logical identifier of the event(s) 
to wait for. 

outContext 

OUT 

ViEvent 

A handle specifying the unique 
occurrence of an event. 

outEventType 

OUT 

ViEventType 

Logical identifier of the event 
actually received. 
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viWaitOnEvent 


Name 

Direction 

Type 

Description 

timeout 

IN 

ViUInt32 

Absolute time period in time 
units that the resource shall wait 
for a specified event to occur 
before returning the time 
elapsed error. 

The time unit is in milliseconds. 

vi 

IN 

ViSession 

Unique logical identifier to a 
session. 


Special Value for outEventType Parameter 


Value 

Description 

VI NULL 

Do not return the type of event. 


Special Value for outContext Parameter 


Value 

Description 

VI NULL 

Do not return an event context. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI_SUCCESS 

Wait terminated successfully on receipt of an event 
occurrence. The queue is empty. 

VI SUCCESS QUEUE 

NEMPTY 

Wait terminated successfully on receipt of an event 
notification. There is still at least one more event 
occurrence of the specified inEventType type 
available for this session. 
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VISA Language Reference 

viWaitOnEvent 


See Also 


Error Codes 

Description 

VI ERROR INV EVENT 

Specified event type is not supported by the 
resource. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NENABLED 

The session must be enabled for events of the 
specified type to receive them. 

VI ERROR TMO 

Specified event did not occur within the specified 
time period. 


See Chapter 4 - Programming with VISA for more information on event 
handling. 
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viWrite 


Syntax 

Description 

Parameters 


viWrite 


viWrite (ViSession vi, ViBuf buf, ViUInt32 count, 
ViUInt32 retCount) ; 


This function synchronously transfers data to a device. The data to be 
written is in the buffer represented by buf. This function returns only when 
the transfer terminates. Only one synchronous write function can occur at 
any one time. 

If you pass vi_null as the retCount parameter to the viWrite operation, 
the number of bytes transferred will not be returned. This may be useful if it 
is important to know only whether the operation succeeded or failed. 


Name 

Direction 

Type 

Description 

buf 

IN 

ViBuf 

Represents the location of a data block to 
be sent to device. 

count 

IN 

ViUInt32 

Specifies number of bytes to be written. 

retCount 

OUT 

ViUInt32 

Represents the location of an integer that 
will be set to the number of bytes actually 
transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special value for retCount Parameter 


Value 

Description 

VI NULL 

Do not return the number of bytes transferred. 
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Return Values 


See Also 


VISA Language Reference 

viWrite 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Transfer completed. 


Error Codes 

Description 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has 
been lost. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error 
occurred during transfer. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is 
invalid (both are the same value). 

VI ERROR INV SETUP 

Unable to start write function because setup 
is invalid (due to attributes being set to an 
inconsistent state). 

VI ERROR 10 

Unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is 
not currently the controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both 
NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred 
during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred 
during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has 
been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 


viRead 
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viWriteAsync 


Syntax 


Description 


viWriteAsync 

viWriteAsync (ViSession vi, ViBuf buf, ViUInt32 count, 
Vi Job Id job Id) ; 


NOTE 

This function is implemented synchronously in Agilent VISA. 


Write data to device asynchronously. This function asynchronously transfers 
data to a device. The data to be written is in the buffer represented by buf. 
This function normally returns before the transfer terminates. An I/O 
Completion event is posted when the transfer is actually completed. 

This function returns jobld, which you can use either with viTerminate 
to abort the operation, or with an I/O Completion event to identify which 
asynchronous write operation completed. 

Since an asynchronous I/O request could complete before the 
viWriteAsync operation returns and the I/O completion event can be 
distinguished based on the job identifier, an application must be made aware 
of the job identifier before the first moment that the I/O completion event 
could possibly occur. Setting the output parameter jobld before the data 
transfer even begins ensures that an application can always match the jobld 
parameter with the vi_attr_job_id attribute of the I/O completion event. 

If you pass VI_NULL as the jobld parameter to the viWriteAsync 
operation, no jobld will be returned. The value vi_null is a reserved jobld 
and has a special meaning in viTerminate. This option may be useful if 
only one asynchronous operation will be pending at a given time. If multiple 
jobs are queued at the same time on the same session, an application can 
use the jobld to distinguish the jobs, as they are unique within a session. 
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viWriteAsync 


Parameters 


Name 

Direction 

Type 

Description 

vi 

IN 

ViSession 

Unique logical identifier to a session. 

buf 

IN 

ViBuf 

Represents the location of a data block to 
be sent to the device. 

count 

IN 

ViUInt32 

Specifies number of bytes to be written. 

jobld 

OUT 

ViJobld 

Represents the location of a variable that 
will be set to the job identifier of this 
asynchronous write operation. 


Special value for jobld Parameter 


Value 

Description 

VI NULL 

Do not return a job identifier. 


Return Values 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Codes 

Description 

VI SUCCESS 

Asynchronous write operation successfully queued. 

VI SUCCESS SYNC 

Write operation performed synchronously. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR QUEUE ERROR 

Unable to queue write operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 


See Also viRead, viTerminate, viWrite, viReadAsync 
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VISA Language Reference 

viWriteFromFile 


Syntax 

Description 


Parameters 


viWriteFromFile 


viWriteFromFile (ViSession vi, ViConstString fileName, 
ViUInt32 count, ViUInt32 retCount) ; 


Take data from a file and write it out synchronously. This write operation 
synchronously transfers data. The file specified in fileName is opened in 
binary read-only mode and the data (up to end-of-file or the number of bytes 
specified in count) are read. The data is then written to the device. This 
operation returns only when the transfer terminates. 

This operation is useful for sending data that was already processed and/or 
formatted. VISA uses ANSI C file operations, so the mode used by 
viWriteFromFile is "rb". If you pass VI_NULL as the retCount parameter 
to the viWriteFromFile operation, the number of bytes transferred will 
not be returned. This may be useful if it is important to know only whether 
the operation succeeded or failed. 


Name 

Direction 

Type 

Description 

count 

IN 

ViUInt32 

Number of bytes to be written. 

fileName 

IN 

ViConstString 

Name of file to which data will be read. 

retCount 

OUT 

ViUInt32 

Number of bytes actually transferred. 

vi 

IN 

ViSession 

Unique logical identifier to a session. 


Special Value for retCount Parameter 


Value 

Description 

VI NULL 

Do not return the number of bytes transferred. 
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Return Values 


See Also 


VISA Language Reference 

viWriteFromFile 


Type ViStatus This is the function return status. It returns either a 
completion code or an error code as follows. 


Completion Code 

Description 

VI SUCCESS 

Transfer completed. 


Error Codes 

Description 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid 
(both are the same value). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed 
because the resource identified by vi has been 
locked for this kind of access. 

VI ERROR TMO 

Timeout expired before function completed. 

VI ERROR RAW RW PROT 

VIOL 

Violation of raw write protocol occurred during 
transfer. 

VI ERROR RAW RD PROT 

VIOL 

Violation of raw read protocol occurred during 
transfer. 

VI ERROR OUTP PROT 

VIOL 

Device reported input protocol error during 
transfer. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is not 
currently the controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both NRFD and 
NDAC are deasserted). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the specified 
file. Possible reasons include an invalid path or 
lack of access rights. 

VI ERROR FILE 10 

Error occurred while accessing the specified file. 

VI ERROR CONN LOST 

I/O connection for a session has been lost. 


viWrite, viReadToFile 
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VISA Library Information 


This appendix provides general library information for VISA, including: 

■ VISA Type Definitions 

■ VISA Error Codes (Numerical) 

■ VISA Error Codes (Alphabetical) 

■ VISA Error Codes (by Function) 

■ VISA Directories Information 

■ Editing VISA Configuration Information 
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VISA Type Definitions 


VISA Type Definitions 


VISA Data Type 

Type Definition 

Description 

ViUInt32 

unsigned long 

A 32-bit unsigned integer. 

ViPUInt32 

ViUInt32 * 

The location of a 32-bit unsigned integer. 

ViAUInt32 

ViUInt32 * 

The location of a 32-bit unsigned integer. 

Vilnt32 

signed long 

A 32-bit signed integer. 

ViPInt32 

Vilnt32 * 

The location of a 32-bit signed integer. 

ViAInt32 

Vilnt32 * 

The location of 32-bit signed integer. 

ViUIntl6 

unsigned short 

A 16-bit unsigned integer. 

ViPUIntl6 

ViUIntl6 * 

The location of a 16-bit unsigned integer. 

ViAUIntl6 

ViUIntl6 * 

The location of a 16-bit unsigned integer. 

Vilntl6 

signed short 

A 16-bit signed integer. 

ViPIntl6 

Vilntl6 * 

The location of a 16-bit signed integer. 

ViAIntl6 

Vilntl6 * 

The location of 16-bit signed integer. 

ViUInt8 

unsigned char 

An 8-bit unsigned integer. 

ViPUInt8 

ViUInt8 * 

The location of an 8-bit unsigned integer. 

ViAUInt8 

ViUInt8 * 

The location of an 8-bit unsigned integer. 

Vilnt8 

signed char 

An 8-bit signed integer. 

ViPInt8 

Vilnt8 * 

The location of an 8-bit signed integer. 

ViAInt8 

Vilnt8 * 

The location of an 8-bit signed integer. 

ViAddr 

void * 

A type that references another data type. 

ViPAddr 

ViAddr * 

The location of a ViAddr . 

ViChar 

char 

An 8-bit integer representing an ASCII character. 

ViPChar 

ViChar * 

The location of a ViChar. 

ViByte 

unsigned char 

An 8-bit unsigned integer representing an extended 

ASCII character. 

ViPByte 

ViByte * 

The location of a ViByte. 

ViBoolean 

ViUIntl6 

A type that is either vi true or vi false. 

ViPBoolean 

ViBoolean * 

The location of a ViBoolean. 
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VISA Library Information 

VISA Type Definitions 


VISA Data Type 

Type Definition 

Description 

ViBuf 

ViPByte 

The location of a block of data. 

ViPBuf 

ViPByte 

The location of a block of data. 

ViString 

ViPChar 

The location of a NULL-terminated ASCII string. 

ViPString 

ViPChar 

The location of a NULL-terminated ASCII string. 

ViStatus 

Vilnt32 

Values that correspond to VISA-defined completion and 
error codes. 

ViPStatus 

ViStatus * 

The location of the completion and error codes. 

ViRsrc 

ViString 

A ViString type. 

ViPRsrc 

ViString 

A ViString type. 

ViAccessMode 

ViUInt32 

Specifies the different mechanisms that control access 
to a resource. 

ViBusAddress 

ViUInt32 

Represents the system dependent physical address. 

ViBusSize 

ViUInt32 

Represents the system dependent physical address size. 

ViAttr 

ViUInt32 

Identifies an attribute. 

ViVersion 

ViUInt32 

Specifies the current version of the resource. 

ViPVersion 

ViVersion * 

The location of ViVersion. 

ViAttrState 

ViUInt32 

Specifies the type of attribute. 

ViPAttrState 

void * 

The location of ViAttrState. 

ViVAList 

va list 

The location of a list of variable number of 
parameters of differing types. 

ViEventType 

ViUInt32 

Specifies the type of event. 

ViPEventType 

ViEventType * 

The location of a ViEventType. 

ViEventFilter 

ViUInt32 

Specifies filtering masks or other information unique 
to an event. 

ViObject 

ViUInt32 

Contains attributes and can be closed when no longer 
needed. 

ViPObject 

ViObject * 

The location of a ViObject. 

ViSession 

ViObject 

Specifies the information necessary to manage a 
communication channel with a resource. 

ViPSession 

ViPSession * 

The location of a ViSession. 
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VISA Type Definitions 


VISA Data Type 

Type Definition 

Description 

ViFindList 

ViObject 

Contains a reference to all resources found during a 
search operation. 

ViPFindList 

ViFindList * 

The location of a ViFindList. 

ViEvent 

ViObject 

Contains information necessary to process an event. 

ViPEvent 

ViEvent * 

The location of a ViEvent. 

ViHndlr 

ViStatus( *) 
(ViSession# 
ViEventType# 
ViEvent# 

ViAddr) 

A value representing an entry point to an operation for use 
as a callback. 

ViReal32 

float 

A 32-bit# single-precision value. 

ViPReal32 

ViReal32 * 

The location of a 32-bit# single-precision value. 

ViReal64 

double 

A 64-bit# double-precision value. 

ViPReal64 

ViReal64 * 

The location of a 64-bit# double-precision value. 

ViJobld 

ViUInt32 

The location of a variable that will be set to the job 
identifier. 

ViKeyld 

ViString 

The location of a string. 
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VISA Error Codes 


VISA Error Codes 

This section describes VISA Error Codes in three categories: 

■ VISA Error Codes (Numerical) 

■ VISA Error Codes (Alphabetical) 

■ VISA Error Codes (by Function) 

VISA Error Codes (Numerical) 

This table lists VISA completion and error codes in numerical order for hex 
and decimal error values. 


Hex 

Decimal 

VISA Status Code 

Success Codes 

3FFF0002 

1073676290 

VI SUCCESS EVENT EN 

3FFF0003 

1073676291 

VI SUCCESS EVENT DIS 

3FFF0004 

1073676292 

VI SUCCESS QUEUE EMPTY 

3FFF0005 

1073676293 

VI SUCCESS TERM CHAR 

3FFF0006 

1073676294 

VI SUCCESS MAX CNT 

3FFF007D 

1073676413 

VI SUCCESS DEV NPRESENT 

3FFF007E 

1073676414 

VI SUCCESS TRIG MAPPED 

3FFF0080 

1073676416 

VI SUCCESS QUEUE NEMPTY 

3FFF0098 

1073676440 

VI SUCCESS NCHAIN 

3FFF0099 

1073676441 

VI SUCCESS NESTED SHARED 

3FFF009A 

1073676442 

VI SUCCESS NESTED EXCLUSIVE 

3FFF009B 

1073676443 

VI SUCCESS SYNC 


Warning Codes 

3FFF0077 

1073676407 

VI WARN CONFIG NLOADED 

3FFF0082 

1073676418 

VI WARN NULL OBJECT 

3FFF0084 

1073676420 

VI WARN NSUP ATTR STATE 

3FFF0085 

1073676421 

VI WARN UNKNOWN STATUS 

3FFF0088 

1073676424 

VI WARN NSUP BUF 
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VISA Error Codes 


Hex 

Decimal 

VISA Status Code 

Error Codes 

BFFF0000 

-1073807360 

VI ERROR SYSTEM ERROR 

BFFF000E 

-1073807346 

VI ERROR INV OBJECT 

BFFF000F 

-1073807345 

VI ERROR RSRC LOCKED 

BFFF0010 

-1073807344 

VI ERROR INV EXPR 

BFFF0011 

-1073807343 

VI ERROR RSRC NFOUND 

BFFF0012 

-1073807342 

VI ERROR INV RSRC NAME 

BFFF0013 

-1073807341 

VI ERROR INV ACC MODE 

BFFF0015 

-1073807339 

VI ERROR TMO 

BFFF0016 

-1073807338 

VI ERROR CLOSING FAILED 

BFFF001B 

-1073807333 

VI ERROR INV DEGREE 

BFFF001C 

-1073807332 

VI ERROR INV JOB ID 

BFFF001D 

-1073807331 

VI ERROR NSUP ATTR 

BFFF001E 

-1073807330 

VI ERROR NSUP ATTR STATE 

BFFF001F 

-1073807329 

VI ERROR ATTR READONLY 

BFFF0020 

-1073807328 

VI ERROR INV LOCK TYPE 

BFFF0021 

-1073807327 

VI ERROR INV ACCESS KEY 

BFFF0026 

-1073807322 

VI ERROR INV EVENT 

BFFF0027 

-1073807321 

VI ERROR INV MECH 

BFFF0028 

-1073807320 

VI ERROR HNDLR NINSTALLED 

BFFF0029 

-1073807319 

VI ERROR INV HNDLR REF 

BFFF002A 

-1073807318 

VI ERROR INV CONTEXT 

BFFF002F 

-1073807313 

VI ERROR NENABLED 

BFFF0030 

-1073807312 

VI ERROR ABORT 

BFFF0034 

-1073807308 

VI ERROR RAW WR PROT VIOL 

BFFF0035 

-1073807307 

VI ERROR RAW RD PROT VIOL 

BFFF0036 

-1073807306 

VI ERROR OUTP PROT VIOL 

BFFF0037 

-1073807305 

VI ERROR INP PROT VIOL 

BFFF0038 

-1073807304 

VI ERROR BERR 

BFFF003A 

-1073807302 

VI ERROR INV SETUP 

BFFF003B 

-1073807301 

VI ERROR QUEUE ERROR 

BFFF003C 

-1073807300 

VI ERROR ALLOC 

BFFF003D 

-1073807299 

VI ERROR INV MASK 
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VISA Error Codes 


Hex 

Decimal 

VISA Status Code 

BFFF003E 

-1073807298 

VI ERROR IO 

BFFF003F 

-1073807297 

VI ERROR INV FMT 

BFFF0041 

-1073807295 

VI ERROR NSUP FMT 

BFFF0042 

-1073807294 

VI ERROR LINE IN USE 

BFFF0046 

-1073807290 

VI ERROR NSUP MODE 

BFFF004A 

-1073807286 

VI ERROR SRQ NOCCURRED 

BFFF004E 

-1073807282 

VI ERROR INV SPACE 

BFFF0051 

-1073807279 

VI ERROR INV OFFSET 

BFFF0052 

-1073807278 

VI ERROR INV WIDTH 

BFFF0054 

-1073807276 

VI ERROR NSUP OFFSET 

BFFF0055 

-1073807275 

VI ERROR NSUP VAR WIDTH 

BFFF0057 

-1073807273 

VI ERROR WINDOW NMAPPED 

BFFF0059 

-1073807271 

VI ERROR RESP PENDING 

BFFF005F 

-1073807265 

VI ERROR NLISTENERS 

BFFF0060 

-1073807264 

VI ERROR NCIC 

BFFF0061 

-1073807263 

VI ERROR NSYS CNTLR 

BFFF0067 

-1073807257 

VI ERROR NSUP OPER 

BFFF0068 

-1073807256 

VI ERROR INTR PENDING 

BFFF006A 

-1073807254 

VI ERROR ASRL PARITY 

BFFF006B 

-1073807253 

VI ERROR ASRL FRAMING 

BFFF006C 

-1073807252 

VI ERROR ASRL OVERRUN 

BFFF006E 

-1073807250 

VI ERROR TRIG NMAPPED 

BFFF0070 

-1073807248 

VI ERROR NSUP ALIGN OFFSET 

BFFF0071 

-1073807247 

VI ERROR USER BUF 

BFFF0072 

-1073807246 

VI ERROR RSRC BUSY 

BFFF0076 

-1073807242 

VI ERROR NSUP WIDTH 

BFFF0078 

-1073807240 

VI ERROR INV PARAMETER 

BFFF0079 

-1073807239 

VI ERROR INV PROT 

BFFF007B 

-1073807237 

VI ERROR INV SIZE 

BFFF0080 

-1073807232 

VI ERROR WINDOW MAPPED 

BFFF0081 

-1073807231 

VI ERROR NIMPL OPER 

BFFF0083 

-1073807229 

VI ERROR INV LENGTH 

BFFF0091 

-1073807215 

VI ERROR INV MODE 
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VISA Error Codes 


Hex 

Decimal 

VISA Status Code 

BFFF009C 

-1073807204 

VI ERROR SESN NLOCKED 

BFFF009D 

-1073807203 

VI ERROR MEM NSHARED 

BFFF009E 

-1073807202 

VI ERROR LIBRARY NFOUND 

BFFF009F 

-1073807201 

VI ERROR NSUP INTR 

BFFF00A0 

-1073807200 

VI ERROR INV LINE 

BFFF00A1 

-1073807199 

VI ERROR FILE ACCESS 

BFFF00A2 

-1073807198 

VI ERROR FILE IO 

BFFF00A3 

-1073807197 

VI ERROR NSUP LINE 

BFFF00A4 

-1073807196 

VI ERROR NSUP MECH 

BFFF00A5 

-1073807195 

VI ERROR INTF NUM NCONFIG 

BFFF00A6 

-1073807194 

VI ERROR CONN LOST 


VISA Error Codes (Alphabetical) 

This table lists VISA completion and error codes in alphabetical order. 


Codes 

Description 

Success Codes 

VI SUCCESS 

Operation completed successfully. 

VI SUCCESS DEV NPRESENT 

Session opened successfully, but the device at the specified 
address is not responding. 

VI SUCCESS EVENT DIS 

The specified event is already disabled. 

VI SUCCESS EVENT EN 

The specified event is already enabled for at least one of the 
specified mechanisms. 

VI SUCCESS MAX CNT 

The number of bytes specified were read. 

VI SUCCESS NCHAIN 

Event handled successfully. Do not invoke any other handlers on 
this session for this event. 

VI SUCCESS NESTED EXCLUSIVE 

The specified access mode was successfully acquired and this 
session has nested exclusive locks. 

VI SUCCESS NESTED SHARED 

The specified access mode was successfully acquired and this 
session has nested shared locks. 

VI SUCCESS QUEUE EMPTY 

The event queue was empty while trying to discard queued events. 

VI SUCCESS QUEUE NEMPTY 

The event queue is not empty. 
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VISA Error Codes 


Codes 

Description 

VI SUCCESS SYNC 

The read or write operation performed synchronously. 

VI SUCCESS TERM CHAR 

The specified termination character was read. 

VI SUCCESS TRIG MAPPED 

The path from trigSrc to trigDest is already mapped. 

Warning Codes 

VI WARN CONFIG NLOADED 

The specified configuration either does not exist or could not be 
loaded using VISA-specified defaults. 

VI WARN NSUP ATTR STATE 

The attribute state is not supported by this resource. 

VI WARN NSUP BUF 

The specified buffer is not supported. 

VI WARN UNKNOWN STATUS 

The status code passed to the function was unable to be 
interpreted. 

VI WARN UNKNOWN STATUS 

The status code passed to the function was unable to be 
interpreted. 

Error Codes 

VI ERROR ABORT 

Calls in the current process executing on the specified vi are 
aborted. 

VI ERROR ALLOC 

Insufficient system resources to open a session or to allocate the 
buffer(s) or memory block of the specified size. 

VI ERROR ASRL FRAMING 

A framing error occurred during transfer. 

VI ERROR ASRL OVERRUN 

An overrun error occurred during transfer. A character was not 
read from the hardware before the next character arrived. 

VI ERROR ASRL PARITY 

A parity error occurred during transfer. 

VI ERROR ATTR READONLY 

The attribute specified is read-only. 

VI ERROR BERR 

A bus error occurred during transfer. 

VI ERROR CLOSING FAILED 

Unable to deallocate the previously allocated data structures for 
this session. 

VI ERROR CONN LOST 

A TCP connection is dropped as a result of “keep-alives” packets. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the specified file. Possible 
reasons include an invalid path or lack of access rights. 

VI ERROR FILE 10 

An error occurred while accessing the specified file. 

VI ERROR HNDLR NINSTALLED 

A handler is not currently installed for the specified event. The 
session cannot be enabled for the vi hndlr mode of the callback 
mechanism. 
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VISA Error Codes 


Codes 

Description 

VI ERROR INP PROT VIOL 

Input protocol error occurred during transfer. 

VI ERROR INTF NUM NCONFIG 

The interface type is valid but the specified interface number is 
not configured. 

VI ERROR INTR PENDING 

An interrupt is still pending from a previous call. 

VI ERROR INV ACC MODE 

The access mode specified is invalid. 

VI ERROR INV ACCESS KEY 

The requestedKey value passed in is not a valid access key to the 
specified resource. 

VI ERROR INV CONTEXT 

The event context specified is invalid. 

VI ERROR INV DEGREE 

The specified degree is invalid. 

VI ERROR INV EVENT 

The event type specified is invalid for the specified resource. 

VI ERROR INV EXPR 

The expression specified is invalid. 

VI ERROR INV FMT 

The format specifier is invalid for the current argument. 

VI ERROR INV HNDLR REF 

The specified handler reference and/or the user context value 
does not match the installed handler. 

VI ERROR INV JOB ID 

The specified job identifier is invalid. 

VI ERROR INV LENGTH 

The length specified is invalid. 

VI ERROR INV LINE 

The value specified by the line parameter is invalid. 

VI ERROR INV LOCK TYPE 

The specified type of lock is not supported by this resource. 

VI ERROR INV MASK 

The system cannot set the buffer for the given mask, or the 
specified mask does not specify a valid flush operation on the 
read/write resource. 

VI ERROR INV MECH 

The mechanism specified for the event is invalid. 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV OBJECT 

The object reference is invalid. 

VI ERROR INV OFFSET 

The offset specified is invalid. 

VI ERROR INV PARAMETER 

The value of some parameter is invalid. 

VI ERROR INV PROT 

The protocol specified is invalid. 

VI ERROR INV RSRC NAME 

The resources specified are invalid. 

VI ERROR INV SESSION 

The session specified is invalid. 
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VISA Error Codes 


Codes 

Description 

VI ERROR INV SETUP 

The setup specified is invalid, possibly due to attributes being set 
to an inconsistent state, or some implementation-specific 
configuration file is corrupt or does not exist. 

VI ERROR INV SIZE 

The specified size is invalid. 

VI ERROR INV SPACE 

The address space specified is invalid. 

VI ERROR INV WIDTH 

Invalid source or destination width specified. 

VI ERROR 10 

Could not perform read/write function because of an I/O error 
or an unknown I/O error occurred during transfer. 

VI ERROR LIBRARY NFOUND 

A code library required by VISA could not be located or loaded. 

VI ERROR LINE IN USE 

The specified trigger line is in use. 

VI ERROR MEM NSHARED 

The device does not export any memory. 

VI ERROR NCIC 

The session is referring to something other than the controller in 
charge. 

VI ERROR NENABLED 

The session must be enabled for events of the specified type to 
receive them. 

VI ERROR NIMPL OPER 

The given operation is not implemented. 

VI ERROR NLISTENERS 

No listeners are detected. (Both NRFD and NDAC are 
deasserted.) 

VI ERROR NSUP ALIGN OFFSET 

The specified offset is not properly aligned for the access width of 
the operation. 

VI ERROR NSUP ATTR 

The attribute specified is not supported by the specified resource. 

VI ERROR NSUP ATTR STATE 

The state specified for the attribute is not supported. 

VI ERROR NSUP FMT 

The format specifier is not supported for the current argument 
type. 

VI ERROR NSUP INTR 

The interface cannot generate an interrupt on the requested level 
or with the requested statusID value. 

VI ERROR NSUP LINE 

One of the specified lines (trigSrc or trigDest) is not supported by 
this VISA implementation. 

VI ERROR NSUP MECH 

The specified mechanism is not supported for the given event 
type. 

VI ERROR NSUP MODE 

The specified mode is not supported by this VISA implementation. 

VI ERROR NSUP OFFSET 

The offset specified is not accessible. 
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Codes 

Description 

VI ERROR NSUP OPER 

The operation specified is not supported in the given session. 

VI ERROR NSUP VAR WIDTH 

The specified mode is not supported by this VISA implementation. 

VI ERROR NSUP WIDTH 

The specified width is not supported by this hardware. 

VI ERROR NSYS CNTLR 

The interface associated with this session is not the system 
controller. 

VI ERROR OUTP PROT VIOL 

Output protocol error occurred during transfer. 

VI ERROR QUEUE ERROR 

Unable to queue read or write operation. 

VI ERROR RAW RD PROT VIOL 

A violation of raw read protocol occurred during a transfer. 

VI ERROR RAW WR PROT VIOL 

A violation of raw write protocol occurred during a transfer. 

VI ERROR RESP PENDING 

A previous response is still pending, causing a multiple query 
error. 

VI ERROR RSRC BUSY 

The resource is valid, but VISA cannot currently access it. 

VI ERROR RSRC LOCKED 

The specified operation could not be performed because the 
resource identifed by vi has been locked for this kind of access. 

VI ERROR RSRC NFOUND 

The expression specified does not match any device, or resource 
was not found. 

VI ERROR SESN NLOCKED 

The current session did not have any lock on the resource. 

VI ERROR SRQ NOCCURED 

A service request has not been received for the session. 

VI ERROR SYSTEM ERROR 

Unknown system error. 

VI ERROR TMO 

The operation failed to complete within the specified timeout 
period. 

VI ERROR TRIG UNMAPPED 

The path from trigSrc to trigDest is not currently mapped. 

VI ERROR USER BUF 

A specified user buffer is not valid or cannot be accessed for the 
required size. 

VI ERROR WINDOW MAPPED 

The specified session already contains a mapped window. 

VI ERROR WINDOW NMAPPED 

The specified session is not currently mapped. 
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VISA Error Codes (by Function) 

VISA functions are listed in alphabetical order with associated completion 
and error codes for each function. 

viAssertlntrSignal ( vi, mode, statusID) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INTR PENDING 

An interrupt is still pending from a previous call. 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP INTR 

The interface cannot generate an interrupt on the requested 
level or with the requested statusID value. 

VI ERROR NSUP MODE 

The specified mode is not supported by this VISA 
implementation. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viAssertTrigger(w, protocol); 


Codes 

Description 

VI_SUCCESS 

Specified trigger was successfully asserted to the device. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error during transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV PROT 

The protocol specified is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR LINE IN USE 

The specified trigger line is currently in use. 
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Codes 

Description 

VI ERROR NCIC 

vi does not refer to an interface that is currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viAssertUtilSignal ( vi, line) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI ERROR INV LINE 

The value specified by the line parameter is invalid. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before operation completed. 


viBufRead (vi, buf, count, retCount) ; 


Codes 

Description 

VI SUCCESS 

The operation completed successfully and the END indicator 
was received (for interfaces that have END indicators). 

VI SUCCESS TERM CHAR 

The specified termination character was read. 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 
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VISA Error Codes 


Codes 

Description 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are 

VI ERROR INV OBJECT 

the same value). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viBufWrite ( vi, buf, count, retCount) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR INV SETUP 

Unable to start write operation because 
setup is invalid (due to attributes being set 
to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viClear (vi) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 
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VISA Error Codes 


Codes 

Description 

VI ERROR NCIC 

vi does not refer to an interface that is currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viClose (vi) ; 


Codes 

Description 

VI_SUCCESS 

Session closed successfully. 

VI ERROR CLOSING FAILED 

Unable to deallocate the previously allocated data structures 
corresponding to this session or object reference. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 

VI WARN NULL OBJECT 

The specified object reference is uninitialized. 


viDisableEvent (vi, eventType, mechanism) ; 


Codes 

Description 

VI SUCCESS 

Event disabled successfully. 

VI SUCCESS EVENT DIS 

Specified event is already disabled for at least one of the 
specified mechanisms. 

VI ERROR INV EVENT 

Specified event type is not supported by the resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 
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VISA Error Codes 


viDiscardEvents ( vi, eventType, mechanism) ; 


Codes 

Description 

VI_SUCCESS 

Event queue flushed successfully. 

VI SUCCESS QUEUE EMPTY 

Operation completed successfully, but queue empty. 

VI ERROR INV EVENT 

Specified event type is not supported by the resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 


viEnableEvent ( vi, eventType, mechanism, context) ; 


Codes 

Description 

VI SUCCESS 

Event enabled successfully. 

VI SUCCESS EVENT EN 

The specified event is already enabled for at least one of 
the specified mechanisms. 

VI ERROR HNDLR NINSTALLED 

A handler is not currently installed for the specified event. 

The session cannot be enabled for the VI HNDLR mode of 

the callback mechanism. 

VI ERROR INV CONTEXT 

Invalid event context specified. 

VI ERROR INV EVENT 

The specified event type is not supported by the resource. 

VI ERROR INV MECH 

Invalid mechanism specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 

VI ERROR NSUP MECH 

The specified mechanism is not supported for the given 
event type. 


viEventHandler (vi, eventType, context, userHandle) ; 


Codes 

Description 

VI SUCCESS 

Event handled successfully. 
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VISA Error Codes 


viFindNext (find List, instrDesc) ; 


Codes 

Description 

VI SUCCESS 

Resource(s) found. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given findList is not a valid session. 

VI ERROR NSUP OPER 

The given findList does not support this function. 

VI ERROR RSRC NFOUND 

There are no more matches. 


viFindRsrc ( sesn, expr, find List, retcnt, instrDesc) ; 


Codes 

Description 

VI SUCCESS 

Resource(s) found. 

VI ERROR INV EXPR 

Invalid expression specified for search. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given sesn is not a valid session. 

VI ERROR NSUP OPER 

The given sesn does not support this function. 

VI ERROR RSRC NFOUND 

Specified expression does not match any devices. 


viFlush ( vi, mask) ; 


Codes 

Description 

VI SUCCESS 

Buffers flushed successfully. 

VI ERROR INV MASK 

The specified mask does not specify a valid flush operation 
on read/write resource. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform read/write operation because of I/O error. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

The read/write operation was aborted because timeout 
expired while operation was in progress. 
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VISA Error Codes 


viGetAttribute (vi, attribute, attrState) ; 


Codes 

Description 

VI_SUCCESS 

Resource attribute retrieved successfully. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 

VI ERROR NSUP ATTR 

The specified attribute is not defined by the referenced 
resource. 


viGpibCommand ( vi, buf, count, retCount) ; 


Codes 

Description 

VI SUCCESS 

Resource attribute retrieved successfully. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR INV SETUP 

Unable to start write operation because setup is invalid (due 
to attributes being set to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with this session 
is not currently the controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both 

NRFD and NDAC are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before operation completed. 


viGpibControlATN (vi, mode) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 
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VISA Error Codes 


Codes 

Description 

VI ERROR NCIC 

The interface associated with this session is not currently the 
controller in charge. 

VI ERROR NSUP MODE 

The specified mode is not supported by this VISA 
implementation. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viGpibControlREN (vi, mode) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NCIC 

The interface associated with this session is not currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR NSYS CNTLR 

The interface associated with this session is not the system 
controller. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viGpibPassControl ( vi, primAddr, secAddr) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 
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Codes 

Description 

VI ERROR NCIC 

The interface associated with this session is not currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before operation completed. 


viGpibSendIFC (vi ); 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR NSYS CNTLR 

The interface associated with this session is not the system 
controller. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viln8 ( vi, space, offset, val8) ; 
vilnl6 (vi, space, offset, vail6) ; 
viln32 ( vi, space, offset, va!32) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SPACE 

Invalid address space specified. 


344 


Appendix A 

























VISA Library Information 

VISA Error Codes 


Codes 

Description 

VI ERROR NSUP ALIGN OFFSET 

The specified offset is not properly aligned for the access 
width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


vilnstallHandler (vi, eventType, handler, userHandle) ; 


Codes 

Description 

VI_SUCCESS 

Event handler installed successfully. 

VI ERROR HNDLR NINSTALLED 

The handler was not installed. This may be returned if an 
application attempts to install multiple handlers for the same 
event on the same session. 

VI ERROR INV EVENT 

Specified event type is not defined by the resource. 

VI ERROR INV HNDLR REF 

The given handler reference is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 


viLock ( vi, lockType, timeout, requestedKey, accessKey) ; 


Codes 

Description 

VI_SUCCESS 

The specified access mode was successfully acquired. 

VI SUCCESS NESTED EXCLUSIVE 

The specified access mode was successfully acquired 
and this session has nested exclusive locks. 

VI SUCCESS NESTED SHARED 

The specifed access mode was successfully acquired 
and this session has nested shared locks. 

VI ERROR INV ACCESS KEY 

The requestedKey value passed is not a valid access 
key to the specified resource. 

VI ERROR INV LOCK TYPE 

The specified type of lock is not supported by this resource. 

VI ERROR INV OBJECT 

The given object reference is invalid. 
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VISA Error Codes 


Codes 

Description 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR RSRC LOCKED 

The specified type of lock cannot be obtained because the 
resource is already locked with a lock type incompatible 
with the lock requested. 

VI ERROR TMO 

The specified type of lock could not be obtained within the 
specified timeout period. 


viMapAddress (i//, mapSpace, mapBase, mapSize, access, suggested,address) ; 


Codes 

Description 

VI SUCCESS 

Map successful. 

VI ERROR ALLOC 

Unable to allocate window of at least the requested size. 

VI ERROR INV ACC MODE 

Invalid access mode. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR INV SIZE 

Invalid size of window specified. 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP OFFSET 

Specified region is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Could not acquire resource or perform mapping before the 
timer expired. 

VI ERROR WINDOW MAPPED 

The specified session already contains a mapped window. 


346 


Appendix A 
























VISA Library Information 

VISA Error Codes 


viMapTrigger (i//, trigSrc, trigDest, mode) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI SUCCESS TRIG MAPPED 

The path from trigSrc to trigDest is already mapped. 

VI ERROR INV LINE 

One of the specified lines (trigSrc or trigDest) is invalid. 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR LINE IN USE 

One of the specified lines (trigSrc or trigDest) is in use. 

VI ERROR NSUP LINE 

One of the specified lines (trigSrc or trigDest) is not 
supported by this VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before operation completed. 


viMemAlloc ( vi, size, offset) ; 


Codes 

Description 

VI_SUCCESS 

The operation completed successfully. 

VI ERROR ALLOC 

Unable to allocate shared memory block of requested size. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SIZE 

Invalid size specified. 

VI ERROR MEM NSHARED 

The device does not export any memory. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 
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VISA Error Codes 


viMemFree ( vi, offset) ; 


Codes 

Description 

VI_SUCCESS 

The operation completed successfully. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR NSUP OPER 

The given vi does not support this operation. 

VI ERROR WINDOW MAPPED 

The specified offset is currently in use by viMapAddress. 


viMove (vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, destWidth, Lengthy, 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid source or destination offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid source or destination address space specified. 

VI ERROR INV WIDTH 

Invalid source or destination width specified. 

VI ERROR NSUP ALIGN OFFSET 

The specified offset is not properly aligned for the access 
width of the operation. 

VI ERROR NSUP OFFSET 

Invalid source or destination offset is not accessible from this 
hardware. 

VI ERROR NSUP ORDER 

The given vi does not support this operation. 

VI ERROR NSUP VAR WIDTH 

Cannot support source and destination widths that are 
different. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 
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VISA Error Codes 


Codes 

Description 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viMoveAsync ( vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, destWidth, Length, 
job!d)\ 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI SUCCESS SYNC 

Operation performed synchronously. 

VI-ERROR QUEUE 

Unable to queue move operation. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR NSUP ORDER 

The given vi does not support this operation. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viMoveIn8 ( vi, space, offset, length, buf8) ; 
viMoveInl6 (vi, space, offset,! ength, buf16) ; 
viMoveln32 (vi, space, offset, length, buf32) 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid address space specified. 
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Codes 

Description 

VI ERROR NSUP ALIGN OFFSET 

the specified offset is not properly aligned for the access 
width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viMoveOut8 (vi, space, offset, length, buf8) ; 
viMoveOutl 6 ( vi, space, offset, length, buf16) ; 
viMoveOut32 (vi, space, offset, length, buf32) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV LENGTH 

Invalid length specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN OFFSET 

the specified offset is not properly aligned for the access 
width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 
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viOpen (sesn, rsrcName, accessMode, timeout, vi) ; 


Codes 

Description 

VI SUCCESS 

Session opened successfully. 

VI WARN CONFIG NLOADED 

The specified configuration either does not exist or could not 
be loaded using VISA-specified defaults. 

VI ERROR ALLOC 

Insufficient system resources to open a session. 

VI ERROR INTF NUM NCONFIG 

The interface type is valid but the specified interface number 
is not configured. 

VI ERROR INV ACC MODE 

Invalid access mode. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV RSRC NAME 

Invalid resource reference specified. Parsing error. 

VI ERROR INV SESSION 

The given sesn does not identify a valid session. 

VI ERROR NSUP OPER 

The given sesn does not support this function. For VISA, 
this operation is supported only by the Default Resource 
Manager session. 

VI ERROR RSRC BUSY 

The resource is valid, but VISA cannot currently access it. 

VI ERROR RSRC LOCKED 

Specified type of lock cannot be obtained because the 
resource is already locked with a lock type incompatible with 
the lock requested. 

VI ERROR RSRC NFOUND 

Insufficient location information or resource not present in 
the system. 

VI ERROR TMO 

A session to the resource could not be obtained within the 
specified timeout period. 

VI SUCCESS DEV NPRESENT 

Session opened successfully, but the device at the specified 
address is not responding. 
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viOpenDefaultRM (sesn) ; 


Codes 

Description 

VI_SUCCESS 

Session to the Default Resource Manager resource created 
successfully. 

VI ERROR ALLOC 

Insufficient system resources to create a session to the 
Default Resource Manager resource. 

VI ERROR INV SETUP 

Some implementation-specific configuration file is corrupt or 
does not exist. 

VI ERROR SYSTEM ERROR 

The VISA system failed to initialize. 


viOut8 ( vi, space, offset, val8) ; 
viOutl6 (vi, space, offset, vail6) ; 
viOut32 ( vi, space, offset, v a!32) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OFFSET 

Invalid offset specified. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR INV SPACE 

Invalid address space specified. 

VI ERROR NSUP ALIGN OFFSET 

The specified offset is not properly aligned for the access 
width of the operation. 

VI ERROR NSUP OFFSET 

Specified offset is not accessible from this hardware. 

VI ERROR NSUP WIDTH 

Specified width is not supported by this hardware. 
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viParseRsrc ( sesn, rsrcName, intfType, intfNum) ; 


Codes 

Description 

VI_SUCCESS 

Resource string is valid. 

VI ERROR ALLOC 

Insufficient system resources to parse the string. 

VI ERROR INTF NUM NCONFIG 

The interface type is valid but the specified interface number 
is not configured. 

VI ERROR INV RSRC NAME 

Invalid resource reference specified. Parsing error. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR LIBRARY NFOUND 

A code library required by VISA could not be located or 
loaded. 

VI ERROR NSUP OPER 

The given sesn does not support this operation. For VISA, 
this operation is supported only by the Default Resource 
Manager session. 

VI ERROR RSRC NFOUND 

Insufficient location information or resource not present in 
the system. 


viPeek8 ( vi, addr, val8) ; 
viPeekl6 (vi, addr, vail6) ; 
viPeek32 (vi, addr, val32) ; 

These functions do not return any completion or error codes. 

viPoke8 (vi, addr, val8) ; 
vi Poke 16 (vi, addr, vail 6) ; 
viPoke32 (vi, addr, val32) ; 

These functions do not return any completion or error codes. 
viPrintf (vi, writeFmt, argl, arg2) ; 


Codes 

Description 

VI SUCCESS 

Parameters were successfully formatted. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 
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Codes 

Description 

VI ERROR 10 

Could not perform write operation because of I/O error. 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before write operation completed. 


viQueryf (vi, writeFmt, readFmt, argl, arg2) ; 


Codes 

Description 

VI_SUCCESS 

Successfully completed the Query operation. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt or readFmt string is 
invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform read/write operation because of I/O error. 

VI ERROR NSUP FMT 

The format specifier is not supported for current argument 
type. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout occurred before read/write operation completed. 


viRead ( vi, buf, count, retCount) ; 


Codes 

Description 

VI SUCCESS 

The operation completed successfully and the END indicator 
was received (for interfaces that have END indicators). 

VI SUCCESS TERM CHAR 

The specified termination character was read. 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 

VI ERROR ASRL FRAMING 

A framing error occurred during transfer. 
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Codes 

Description 

VI ERROR ASRL OVERRUN 

An overrun error occurred during transfer. A character was 
not read from the hardware before the next character 
arrived. 

VI ERROR ASRL PARITY 

A parity error occurred during transfer. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start read operation because setup is invalid 
(due to attributes being set to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

vi does not refer to an interface that is currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error occurred during 
transfer. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viReadAsync ( vi, buf, count, jobld ) ; 


Codes 

Description 

VI SUCCESS 

Asynchronous read operation successfully queued. 

VI SUCCESS SYNC 

Read operation performed synchronously. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR QUEUE ERROR 

Unable to queue read operation. 
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Codes 

Description 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viReadSTB ( vi, status) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR INV SETUP 

Unable to start operation because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR NCIC 

vi does not refer to an interface that is currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR SRQ NOCCURRED 

Service request has not been received for the session. 

VI ERROR TMO 

Timeout expired before function completed. 


viReadToFile {vi, fileName, count, retCount) ; 


Codes 

Description 

VI_SUCCESS 

The function completed successfully and the END indicator 
was received (for interfaces that have END indicators). 

VI SUCCESS TERM CHAR 

The specified termination character was read. 

VI SUCCESS MAX CNT 

The number of bytes read is equal to count. 
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Codes 

Description 

VI ERROR ASRL FRAMING 

A framing error occurred during transfer. 

VI ERROR ASRL OVERRUN 

An overrun error occurred during transfer. A character was 
not read from the hardware before the next character 
arrived. 

VI ERROR ASRL PARITY 

A parity error occurred during transfer. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has been lost. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the specified file. 
Possible reasons include an invalid path or lack of access 
rights. 

VI ERROR FILE 10 

An error occurred while accessing the specified file. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR INV SETUP 

Unable to start read function because setup is invalid (due to 
attributes being set to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is not currently the 
controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error occurred during 
transfer. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 
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viScanf ( vi, readFmt, argl, arg2) ; 


Codes 

Description 

VI_SUCCESS 

Data was successfully read and formatted into arg 
parameter(s). 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform read operation because of I/O error. 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before read operation completed. 


viSetAttribute ( vi, attribute, attrState) ; 


Codes 

Description 

VI_SUCCESS 

All attribute values set successfully. 

VI ERROR ATTR READONLY 

The specified attribute is read-only. 

VI ERROR ATTR READONLY 

The specified attribute is read-only. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR NSUP ATTR 

The specified attribute is not defined by the referenced 
resource. 

VI ERROR NSUP ATTR STATE 

The specified state of the attribute is not valid, or is not 
supported as defined by the resource. 

VI ERROR RSRC LOCKED 

The specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI WARN NSUP ATTR STATE 

Although the specified state of the attribute is valid, it is not 
supported by this resource implementation 
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viSetBuf ( vi, mask, size) ; 


Codes 

Description 

VI_SUCCESS 

Buffer size set successfully. 

VI WARN NSUP BUF 

The specified buffer is not supported. 

VI ERROR ALLOC 

The system could not allocate the buffer(s) of the specified 
size because of insufficient system resources. 

VI ERROR INV MASK 

The system cannot set the buffer for the given mask. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viSPrintf ( vi, buf, writeFmt, argl, arg2, ...); 


Codes 

Description 

VI_SUCCESS 

Parameters were successfully formatted. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient system resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 
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viSScanf ( vi, buf, readFmt, argl, arg2, ...); 


Codes 

Description 

VI_SUCCESS 

Data were successfully read and formatted into arg 
parameter(s). 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient system resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viStatusDesc ( vi, status, desc) ; 


Codes 

Description 

VI_SUCCESS 

Description successfully returned. 

VI WARN UNKNOWN STATUS 

The status code passed to the function could not be 
interpreted. 


viTerminate ( vi, degree, jobld) ; 


Codes 

Description 

VI_SUCCESS 

Request serviced successfully. 

VI ERROR ABORT 

Calls in the current process executing on the specified vi 
are aborted. 

VI ERROR INV DEGREE 

Invalid degree specified. 

VI ERROR INV JOB ID 

Invalid job identifier specified. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 
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viUninstallHandler (vi, eventType, handler, userHandle) ; 


Codes 

Description 

VI SUCCESS 

Event handler successfully uninstalled. 

VI ERROR HNDLR NINSTALLED 

A handler is not currently installed for the specified event. 

VI ERROR INV EVENT 

Specified event type is not supported by the resource. 

VI ERROR INV HNDLR REF 

Either the specified handler reference or the user context 
value (or both) does not match any installed handler. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 


viUnlock ( vi) ; 


Codes 

Description 

VI SUCCESS 

The lock was successfully relinquished. 

VI SUCCESS NESTED EXCLUSIVE 

The call succeeded, but this session still has nested 
exclusive locks. 

VI SUCCESS NESTED SHARED 

The call succeeded, but this session still has nested shared 
locks. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR SESN NLOCKED 

The current session did not have any lock on the resource. 

VI ERROR SESN NLOCKED 

The current session did not have any lock on the resource. 


viUnmapAddress (vi) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR WINDOW NMAPPED 

The specified session is not currently mapped. 
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viUnmapTrigger ( vi, trigSrc, trigDest ) ; 


Codes 

Description 

VI_SUCCESS 

Operation completed successfully. 

VI ERROR INV LINE 

One of the specified lines (trigSrc or trigDest) is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP LINE 

One of the specified lines (trigSrc or trigDest) is not 
supported by this VISA implementation. 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TRIG UNMAPPED 

The path from trigSrc to trigDest is not currently mapped. 


viVPrintf ( vi, writeFmt, params) ; 


Codes 

Description 

VI SUCCESS 

Parameters were successfully formatted. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform write operation because of I/O error. 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before write operation completed. 
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viVQueryf (w, writeFmt, readFmt, params) ; 


Codes 

Description 

VI SUCCESS 

Successfully completed the Query operation. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt or readFmt string is 
invalid. 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform read/write operation because of I/O error. 

VI ERROR NSUP FMT 

The format specifier is not supported for current argument 
type. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout occurred before read/write operation completed. 


viVScanf ( vi, readFmt, params) ; 


Codes 

Description 

VI SUCCESS 

Data were successfully read and formatted into arg 
parameter(s). 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR 10 

Could not perform read operation because of I/O error. 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation not performed because the resource 
identified by vi has been locked for this kind of access. 

VI ERROR TMO 

Timeout expired before read operation completed. 
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viVSPrintf (vi, buf, writeFmt, params) ; 


Codes 

Description 

VI_SUCCESS 

Parameters were successfully formatted. 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the writeFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP FMT 

A format specifier in the writeFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


vivsscanf (vi, buf, readFmt, params) ; 


Codes 

Description 

VI_SUCCESS 

Data were successfully read and formatted into arg 
parameter(s). 

VI ERROR ALLOC 

The system could not allocate a formatted I/O buffer 
because of insufficient resources. 

VI ERROR INV FMT 

A format specifier in the readFmt string is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP FMT 

A format specifier in the readFmt string is not supported. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viVxiCommandQuery ( vi, mode, cmd, response ) ; 


Codes 

Description 

VI SUCCESS 

Operation completed successfully. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error occurred during 
transfer. 
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Codes 

Description 

VI ERROR INV MODE 

The value specified by the mode parameter is invalid. 

VI ERROR INV SESSION 

VI ERROR INV OBJECT 

The given session or object reference is invalid (both are the 
same value). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an output protocol error occurred during 
transfer. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RESP PENDING 

A previous response is still pending, causing a multiple query 
error. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 


viWaitOnEvent ( vi, ineventType, timeout, outEventType, outcontext ) ; 


Codes 

Description 

VI SUCCESS 

Wait terminated successfully on receipt of an event 
occurrence. The queue is empty. 

VI SUCCESS QUEUE NEMPTY 

Wait terminated successfully on receipt of an event 
notification. There is still at least one more event occurrence 
available for this session. 

VI ERROR INV EVENT 

Specified event type is not supported by the resource. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 

VI ERROR TMO 

Specified event did not occur within the specified time 
period. 
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viWrite ( vi, buf, count, retCount ) ; 


Codes 

Description 

VI_SUCCESS 

Transfer completed. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has been lost. 

VI ERROR INP PROT VIOL 

Device reported an input protocol error occurred during 
transfer. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given vi does not identify a valid session. 

VI ERROR INV SETUP 

Unable to start read operation because setup is invalid 
(due to attributes being set to an inconsistent state). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

vi does not refer to an interface that is currently the 
controller in charge. 

VI ERROR NLISTENERS 

No listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW WR PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before operation completed. 


viWriteAsync ( vi, buf, count, jobld) ; 


Codes 

Description 

VI_SUCCESS 

Asynchronous write operation successfully queued. 

VI SUCCESS SYNC 

Write operation performed synchronously. 

VI ERROR INV OBJECT 

The given object reference is invalid. 

VI ERROR INV SESSION 

The given session is invalid. 

VI ERROR QUEUE ERROR 

Unable to queue write operation. 
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Codes 

Description 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 


viWriteFromFile ( vi, fileName, count, retCount ) ; 


Codes 

Description 

VI SUCCESS 

Transfer completed. 

VI ERROR BERR 

Bus error occurred during transfer. 

VI ERROR CONN LOST 

The I/O connection for the given session has been lost. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the specified file. 
Possible reasons include an invalid path or lack of access 
rights. 

VI ERROR FILE ACCESS 

An error occurred while trying to open the specified file. 
Possible reasons include an invalid path or lack of access 
rights. 

VI ERROR FILE 10 

An error occurred while accessing the specified file. 

VI ERROR INV SESSION 

The given session or object reference is invalid (both are the 

VI ERROR INV OBJECT 

same value). 

VI ERROR 10 

An unknown I/O error occurred during transfer. 

VI ERROR NCIC 

The interface associated with the given vi is not currently the 
controller in charge. 

VI ERROR NLISTENERS 

No Listeners condition is detected (both NRFD and NDAC 
are deasserted). 

VI ERROR NSUP OPER 

The given vi does not support this function. 

VI ERROR OUTP PROT VIOL 

Device reported an input protocol error during transfer. 

VI ERROR RAW RD PROT VIOL 

Violation of raw read protocol occurred during transfer. 

VI ERROR RAW RW PROT VIOL 

Violation of raw write protocol occurred during transfer. 

VI ERROR RSRC LOCKED 

Specified operation could not be performed because the 
resource identified by vi has been locked for this kind of 
access. 

VI ERROR TMO 

Timeout expired before function completed. 
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VISA Directories Information 

This section provides information about the location of VISA software files. 
This information can be used as reference or for removing VISA software 
from your system, if necessary. 


NOTE 

For Windows systems, use “Add/Remove Programs” from the Windows 
Control Panel to remove files, rather than deleting them manually. 


Windows Directory Structure 

The \IX\plug&play alliance defines directory structures to be used with the 
Windows system framework. As shown in the following figure, VISA files 
are automatically installed into the WIN95 subdirectory on Windows 95, 
Windows 98, or Windows Me or into the WINNT subdirectory on Windows 
2000 or Windows NT. The [VXIPNPPATH] defaults to \Program Files\VISA, 
but can be changed during software installation. 

The VISA32.DLL file is stored in the \WINDOWS\SYSTEM subdirectory 
(Windows 95, Windows 98, or Windows Me) or in the \WINNT\SYSTEM32 
subdirectory (Windows 2000 or Windows NT). For Windows systems, the 
VISA path can be displayed by clicking the blue 10 icon (near the clock on 
the Windows taskbar). Then, select View Documentation and then 
Installation Information to view a dialog box that contains the 
VISA path information. A typical display follows. 


||||B| Agilent IO Libraries Installation and Path Information 

xj 



Version K, 01.00.00 




Agilent SICL: Installed 

Agilent VISA: Installed as primary VISA 

non-Agilent VISA: Not Installed 




SICL Path: 'C:\Program Files\Agilent\IO Libraries' 

VISA Path: 'C:\Program Files\VISA' 

Registry Path: ’HKEY_LOCAL_MACHINE\SOFTWARE\Agilent\IO Libraries\CurrentVersion' 



| 

I ok I 



\ 




) 
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HP-UX Directory 
Structure 


[VXIPNPPATH] 

-KBASE 

-WIN95 


BIN 

LIB 


BC 

MSC 


— INCLUDE 

— AGVISA 

L SAMPLES 

— <INSTRUMENT> 


WINNT 



The VXI plug&play alliance defines a directory structure to be used with the 
UNIX system framework. VISA is automatically installed into the following 
directory structure on HP-UX 10.20. The [opt] is an optional path that you 
can change during the software installation. 
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opt 

L 


vxipnp 


— kbase 
'— hpux 


— bin 


— lib 

— include 

— hpvisa 

I- share 


I— <instrument> 



— examples 

— man 

— help 


Editing the VISA Configuration 

When the Agilent 10 Libraries are configured, certain values are used as 
defaults in the VISA configuration. In some cases, the default values may 
affect your system’s performance. 

If you are having system performance problems, you may need to edit the 
configuration and change some default values. This section describes how 
to edit the configuration for VISA on Windows 95, Windows 98, Windows 
Me, Windows 2000, and Windows NT, and on HP-UX. 


When you first configured the Agilent 10 Libraries, the default configuration 
specified that all VISA devices would be identified at runtime. However, this 
configuration is not ideal for all users. 

If you are experiencing performance problems, particularly during 
viFindRsrc calls, you may want to change the VISA configuration to 
identify devices during configuration. This may be especially helpful if you 
are using a VISA LAN client. To edit the default VISA configuration on 
Windows 95/98/Me/2000 or Windows NT: 
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1 If you have not already done so, start Windows 95/98/2000/Me or 
Windows NT. 

2 Run the 10 Config utility from the Agilent 10 Libraries program 
group or from the blue 10 icon on the taskbar (use Run io 
Config from the icon) . 

3 Select the interface to be configured from the Configured 
Interfaces box and click the Edit button. The Interface Edit 
window is now displayed. 

4 Click the Edit VISA Config button at the bottom of the window. 

The dialog box which allows you to add devices is now displayed. 
You can now manually identify devices by clicking the Add Device 
button and entering the device address. 


NOTE 

To turn off the default of identifying devices at runtime, unselect the 
Identify devices at run-time box at the top of the dialog box. 


5 At this time, you may also click the Auto Add Devices button at the 
bottom of the screen to automatically check for devices. If you 
select this button, the utility will prompt you to make sure all devices 
are connected and turned on. Once this process is complete, you 
may edit this list with the Add Device and Remove Device buttons. 

6 Once you have completed adding or removing devices, select the 
OK button to exit the window. Then exit the 10 Config utility to save 
the changes you have made. 


Editing on HP-UX When you first configured the Agilent 10 Libraries, the default configuration 
specified that all VISA devices would be identified at runtime. However, this 
is not ideal for all users. If you are experiencing performance problems, 
particularly during viOpenDefaultRM, you may want to change the 
VISA configuration to identify devices during configuration. 

To edit the default VISA configuration on HP-UX, use the following 
command to run the visacfg utility: 

/opt/vxipnp/hpux/hpvisa/visacfg 

Follow the instructions provided in the utility. When prompted, select the 
Add Device button and add all devices that will be used. 
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VISA Resource Classes 


This appendix describes VISA resource classes, including resource 
overviews, attributes, events, and operations. This appendix includes: 

■ Resource Classes Overview 

■ Instrument Control (INSTR) Resource 

■ Memory Access (MEMACC) Resource 

■ GPIB Bus Interface (INTFC) Resource 

■ VXI Mainframe Backplane (BACKPLANE) Resource 

■ Servant Device-Side (SERVANT) Resource 

■ TCPIP Socket (SOCKET) Resource 


NOTE 

Although the Servant Device-Side (SERVANT) Resource is defined by 
the VXIplug&play Systems Alliance Specification and is described in this 
Appendix, the SERVANT Resource is not supported in Agilent VISA. 
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Resource Classes Overview 

This section summarizes VISA resource classes and shows applicable 
interface types for each resource class. 

Resource Classes vs. Interface Types 

The following table shows the six resource classes that a complete VISA 
system, fully compliant with the VXIplug&play Systems Alliance 
specification, can implement. Since not all VISA implementations may 
implement all resource classes for all interfaces, the following table also 
shows the interfaces applicable to various resource classes. 


Resource Class 

Interface Types 

Resource Class Description 

Instrument Control (INSTR) 

Generic, GPIB, GPIB- 
VXI, Serial, TCPIP, VXI 

Device operations (reading, writing, 
triggering, etc.). 

GPIB Bus Interface 
(INTFC) 

Generic, GPIB 

Raw GPIB interface operations 
(reading, writing, triggering, etc.). 

Memory Access 
(MEMACC) 

Generic, GPIB-VXI, VXI 

Address space of a memory-mapped 
bus such as the VXIbus. 

VXI Mainframe Backplane 
(BACKPLANE) 

Generic, GPIB-VXI, VXI 
(GPIB-VXI Backplane 
not supported) 

VXI-defined operations and 
properties of each backplane (or 
chassis) in a VXIbus system. 

Servant Device-Side 
Resource (SERVANT) 

Not Supported 
(GPIB, VXI, TCPIP) 

Operations and properties of the 
capabilities of a device and a device's 
view of the system in which it exists. 

TCPIP Socket 
(SOCKET) 

Generic, TCPIP 

Operations and properties of a raw 
network socket connection using 
TCPIP. 
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Interface Types vs. Resource Classes 

This table shows the five interface types supported by Agilent VISA and the 
associated Resource Classes for each interface type. 


Interface Type 

Supported Resource Classes 

ASRL 

Instrument Control (INSTR) 

GPIB 

Instrument Control (INSTR) 

GPIB Bus Interface (INTFC) 

GPIB-VXI 

Instrument Control (INSTR) 

Memory Access (MEMACC) 

TCPIP 

Instrument Control (INSTR) 

TCPIP Socket (SOCKET) 

VXI 

Instrument Control (INSTR) 

Memory Access (MEMACC) 

VXI Mainframe Backplane (BACKPLANE) 


Resource Class Descriptions 

The following sections describe each of the six Resource Classes supported 
by VISA. (As noted, the SERVANT Resource Class is not supported by 
Agilent VISA. The description for each Resource Class includes: 

■ Resource Overview 

■ Resource Attributes 

■ Resource Events 

■ Resource Operations (Functions) 


NOTE 

Attributes are local or global. A local attribute only affects the session 
specified. A global attribute affects the specified device from any session. 
Attributes can also be read only (RO) and read/write (RW). 

The Generic Attibutes listed apply to all listed interface types. For 
example, vi_attr_intf_num is listed as a Generic INSTR Resource 
Attribute, so vi_attr_intf_num applies to the GPIB, GPIB-VXI, VXI, 
ASRL, and TCPIP interfaces as well. 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Instrument Control (INSTR) Resource 

This section describes the Instrument Control (INSTR) Resource that is 
provided to encapsulate the various operations of a device (reading, writing, 
triggering, etc.). 

INSTR Resource Overview 

The Instrument Control (INSTR) Resource, like any other resource, defines 
the basic operations and attributes of the VISA Resource Template. For 
example, modifying the state of an attribute is done via the operation 
viSetAttribute, which is defined in the VISA Resource Template. 

Although the INSTR resource does not have viSetAttribute listed in its 
operations, it provides the operation because it is defined in the VISA 
Resource Template. From this basic set, each resource adds its specific 
operations and attributes that allow it to perform its dedicated task, such as 
sending a string to a message-based device. 

The INSTR Resource lets a controller interact with the device associated 
with this resource, by providing the controller with services to send blocks of 
data to the device, request blocks of data from the device, send the device 
clear command to the device, trigger the device, and find information about 
the device's status. In addition, it allows the controller to access registers on 
devices that reside on memory-mapped buses. 


Appendix B 


377 
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Instrument Control (INSTR) Resource 


INSTR Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic INSTR Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF VXI 

VI INTF GPIB 

VI INTF GPIB VXI 

VI INTF ASRL 

VI INTF TCPIP 

N/A 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR 10 PROT 

RW 

Local 

ViUIntl6 

VI NORMAL 

VI FDC 

VI HS488 

VI PROT 488 2 STRS 

VI NORMAL 

VI ATTR RD BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH DISABLE 

VI FLUSH 

DISABLE 

VI ATTR SEND END 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI TRUE 

VI ATTR SUPPRESS 

END EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR TERMCHAR 

RW 

Local 

ViUInt8 

0 to FF 

OA h (linefeed) 

VI ATTR TERMCHAR 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VI ATTR TRIG ID 

RW* 

Local 

Vilntl6 

VI TRIG SW; 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

VI TRIG SW 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic INSTR Resource Attributes (continued) 

VI ATTR WR BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH WHEN FULL 

VI FLUSH 

WHEN FULL 

VI ATTR DMA ALLOW 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR FILE 

APPEND EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR GPIB 

PRIMARY ADDR 

RO 

Global 

ViUIntl6 

Oto 30 

N/A 

VI ATTR GPIB 

SECONDARY ADDR 

RO 

Global 

ViUIntl6 

Oto 31, 

VI NO SEC ADDR 

N/A 

VI ATTR GPIB 

READDR EN 

RW 

Local 

Viboolean 

VI TRUE 

VI FALSE 

VI TRUE 

VI ATTR GPIB 

UNADDR EN 

RW 

Local 

Viboolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR GPIB 

REN STATE 

RO 

Global 

ViUIntl6 

VI STATE UNKNOWN 

VI STATE ASSERTED 

VI STATE UNASSERTED 

N/A 

VXI and GPIB-VXI Specific INSTR Resource Attributes 

VI ATTR MAINFRAME 

LA 

RO 

Global 

Vilntl6 

0 to 255; 

VI UNKNOWN LA 

N/A 

VI ATTR MANF ID 

RO 

Global 

ViUIntl6 

0 to FFF h 

N/A 

VI ATTR MEM BASE 

RO 

Global 

ViBusAddr 

ess 

N/A 

N/A 

VI ATTR MEM SIZE 

RO 

Global 

ViBusSize 

N/A 

N/A 

VI ATTR MEM SPACE 

RO 

Global 

ViUIntl6 

VI A16 SPACE 

VI A24 SPACE 

VI A32 SPACE 

VI A16 

SPACE 

VI ATTR MODEL CODE 

RO 

Global 

ViUIntl6 

Oto FFFF h 

N/A 

VI ATTR SLOT 

RO 

Global 

Vilntl6 

Oto 12; 

VI UNKNOWN SLOT 

N/A 

VI ATTR VXI LA 

RO 

Global 

Vilntl6 

Oto 511 

N/A 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

VXI and GPIB-VXI Specific INSTR Resource Attributes (continued) 

VI ATTR CMDR LA 

RO 

Global 

Vilntl6 

0 to 255; 

VI UNKNOWN LA 

N/A 

VI ATTR IMMEDIATE 

SERV 

RO 

Global 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR FDC CHNL 

RW 

Local 

ViUIntl6 

0 to 7 

N/A 

VI ATTR FDC GEN 

SIGNAL EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR FDC MODE 

RW 

Local 

ViUIntl6 

VI FDC NORMAL 

VI FDC STREAM 

VI FDC 

NORMAL 

VI ATTR FDC USE 

PAIR 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR SRC 

INCREMENT 

RW 

Local 

Vilnt32 

Oto 1 

1 

VI ATTR DEST 

INCREMENT 

RW 

Local 

Vilnt32 

Oto 1 

1 

VI ATTR WIN 

ACCESS 

RO 

Local 

ViUIntl6 

VI NMAPPED 

VI USE OPERS 

VI DEREF ADDR 

VI 

NMAPPED 

VI ATTR WIN BASE 

ADDR 

RO 

Local 

ViBusAddr 

ess 

N/A 

N/A 

VI ATTR WIN SIZE 

RO 

Local 

ViBusSize 

N/A 

N/A 

VI ATTR SRC BYTE 

ORDER 

RW 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 

VI ATTR DEST 

BYTE ORDER 

RW 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 

VI ATTR WIN 

BYTE ORDER 

RW* 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

VXI and GPIB-VXI Specif 

ic INSTR Resourc 

e Attributes (c 

ontinued) 



VI_ATTR_SRC_ 
ACCESS PRIV 


RW 


Local 


ViUIntl6 


VI_DATA_NPRIV 
VI-DATA_PRIV 
VI_PROG_NPRIV 
VI_PROG_PRIV 
VI_BLCK_NPRIV 
VI_BLCK_PRIV 
VI_D 6 4_NPRIV 
VI D64 PRIV 


VI-DATA_ 

PRIV 


VI_ATTR_DEST_ 
ACCESS PRIV 


RW 


Local 


ViUIntl6 


VI_DATA_NPRIV 
VI-DATA_PRIV 
VI_PROG_NPRIV 
VI_PROG_PRIV 
VI_BLCK_NPRIV 
VI_BLCK_PRIV 
VI_D 6 4_NPRIV 
VI D64 PRIV 


VI-DATA_ 

PRIV 


VI_ATTR_WIN_ 
ACCESS PRIV 


RW* 


Local 


ViUIntl6 


VI_DATA_NPRIV 
VI-DATA_PRIV 
VI_PROG_NPRIV 
VI_PROG_PRIV 
VI_BLCK_NPRIV 
VI BLCK PRIV 


VI-DATA_ 

PRIV 


VI_ATTR_VXI_DEV_ 

CLASS 


RO 


Global 


ViUIntl6 


VI_VXI_CLASS_MEMORY 
VI_VXI_CLASS_EXTENDED 
VI_VXI_CLASS_MESSAGE 
VI_VXI_CLASS_REGISTER 
VI VXI CLASS OTHER 


N/A 


VI_ATTR_MANF_ 

NAME 


RO 


Global 


ViString 


N/A 


N/A 


VI_ATTR_MODEL_ 

NAME 


RO 


Global 


ViString 


N/A 


N/A 


GPIB-VXI Specific INSTR Resource Attribute 


VI ATTR INTF 

RO 

Global 

ViUIntl6 

Oto FFFF h 

VI ATTR 

PARENT NUM 





INTF 






PARENT NUM 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

ASRL Specific INSTR Resource Attribute 

VI ATTR ASRL 

AVAIL NUM 

RO 

Global 

ViUInt32 

Oto FFFFFFFF h 

0 

VI ATTR ASRL BAUD 

RW 

Global 

ViUInt32 

Oto FFFFFFFF h 

9600 

VI ATTR ASRL DATA 

BITS 

RW 

Global 

ViUIntl6 

5 to 8 

8 

VI ATTR ASRL 

PARITY 

RW 

Global 

ViUIntl6 

VI ASRL PAR NONE 

VI ASRL PAR ODD 

VI ASRL PAR EVEN 

VI ASRL PAR MARK 

VI ASRL PAR SPACE 

VI ASRL 

PAR NONE 

VI ATTR ASRL STOP 

BITS 

RW 

Global 

ViUIntl6 

VI ASRL STOP ONE 

VI ASRL STOP TWO 

VI ASRL 

STOP ONE 

VI ATTR ASRL FLOW 

CNTRL 

RW 

Global 

ViUIntl6 

VI ASRL FLOW NONE 

VI ASRL FLOW XON XOFF 

VI ASRL FLOW RTS CTS 

VI ASRL FLOW DTR DSR 

VI ASRL 

FLOW NONE 

VI ATTR ASRL END 

IN 

RW 

Local 

ViUIntl6 

VI ASRL END NONE 

VI ASRL END LAST BIT 

VI ASRL END TERMCHAR 

VI ASRL 

END 

TERMCHAR 

VI ATTR ASRL END 

OUT 

RW 

Local 

ViUIntl6 

VI ASRL END NONE 

VI ASRL END LAST BIT 

VI ASRL END TERMCHAR 

VI ASRL END BREAK 

VI ASRL 

END NONE 

VI ATTR ASRL CTS 

STATE 

RO 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR ASRL DCD 

STATE 

RO 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR ASRL DSR 

STATE 

RO 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR ASRL RI 

STATE 

RO 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 
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Instrument Control (INSTR) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

ASRL Specific INSTR Resource Attribute (continued) 

VI ATTR ASRL DTR 

STATE 

RW 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR ASRL RTS 

STATE 

RW 

Global 

ViUIntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR ASRL 

REPLACE CHAR 

RW 

Local 

ViUInt8 

0 to FF(-, 

0 

VI ATTR ASRL XON 

CHAR 

RW 

Local 

ViUInt8 

0 to FF[-| 

<Ctrl+Q> 

(Hh) 

VI ATTR ASRL XOFF 

CHAR 

RW 

Local 

ViUInt8 

0 to FFf, 

<Ctrl+S> 

(13 h ) 

TCPIP Specific INSTR Resource Attributes 

VI ATTR TCPIP ADDR 

RW 

Global 

ViString 

N/A 

N/A 

VI ATTR TCPIP HOST 

NAME 

RW 

Global 

ViString 

N/A 

N/A 

VI ATTR TCPIP 

DEVICE NAME 

RW 

Global 

ViString 

N/A 

N/A 


* The attribute vi_attr_trig_id is RW (readable and writeable) when the corresponding session is not 
enabled to receive trigger events. When the session is enabled to receive trigger events, the attribute 
vi_attr_trig_id is RO (read only). 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


INSTR Resource Attribute Descriptions 


Attribute Name 

Description 

Generic INSTR Resource Attributes 

VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR 10 PROT 

Specifies which protocol to use. In VXI systems, for example, 
you can choose between normal word serial or fast data channel 
(FDC). In GPIB, you can choose between normal and high-speed 
(HS488) data transfers. In ASRL systems, you can choose 
between normal and 488-style transfers, in which case the 
viAssertTrigger/viReadSTB/viClear operations send 
488.2-defined strings. 

VI ATTR RD BUF OPER MODE 

Determines the operational mode of the read buffer. When the 
operational mode is set to vi flush disable (default), the 
buffer is flushed only on explicit calls to viFlush. If the 
operational mode is set to vi flush on access, the buffer is 
flushed every time a viScanf operation completes. 

VI ATTR SEND END EN 

Whether to assert END during the transfer of the last byte of the 
buffer. 

VI ATTR SUPPRESS END EN 

Whether to suppress the END indicator termination. If this 
attribute is set to vi true, the END indicator does not terminate 
read operations. If this attribute is set to vi false, the END 
indicator terminates read operations. 

VI ATTR TERMCHAR 

Termination character. When the termination character is read 
and vi attr termchar en is enabled during a read 
operation, the read operation terminates. 

VI ATTR TERMCHAR EN 

Flag that determines whether the read operation should terminate 
when a termination character is received. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value 
of vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 

VI ATTR TRIG ID 

Identifier for the current triggering mechanism. 
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Instrument Control (INSTR) Resource 

Attribute Name 

Description 


Generic INSTR Resource Attributes (continued) 


VI ATTR WR BUF OPER MODE 

Determines the operational mode of the write buffer. When the 
operational mode is set to vi flush when full (default), the 
buffer is flushed when an END indicator is written to the buffer 
or when the buffer fills up. 

If the operational mode is set to vi flush on access, the 
write buffer is flushed under the same conditions, and also every 
time a viPrintf operation completes. 

VI ATTR DMA ALLOW EN 

This attribute specifies whether I/O accesses should use 

DMA (vi true) or Programmed I/O (vi false). In some 
implementations, this attribute may have global effects even 
though it is documented to be a local attribute. Since this affects 
performance and not functionality, that behavior is acceptable. 

VI ATTR FILE APPEND EN 

This attribute specifies whether viReadToFile will overwrite 
(truncate) or append when opening a file. 


GPIB and GPIB-VXI Specific INSTR Resource Attributes 


VI ATTR GPIB PRIMARY ADDR 

Primary address of the GPIB device used by the given session. 

VI ATTR GPIB SECONDARY ADDR 

Secondary address of the GPIB device used by the given session. 

VI ATTR GPIB READDR EN 

This attribute specifies whether to use repeat addressing before 
each read or write operation. 

VI ATTR GPIB UNADDR EN 

This attribute specifies whether to unaddress the device (UNT and 
UNL) after each read or write operation. 

VI ATTR GPIB REN STATE 

This attribute returns the current state of the GPIB REN interface 
line. 


VXI and GPIB-VXI Specific INSTR Resource Attributes 


VI ATTR MAINFRAME LA 

This is the logical address of a given device in the mainframe, 
usually the device with the lowest logical address. Other possible 
values include the logical address of the Slot 0 controller or of the 
parent-side extender. Often, these are all the same value. 

The purpose of this attribute is to provide a unique ID for each 
mainframe. A VISA manufacturer can choose any of these 
values, but must be consistent across mainframes. If this value 
is not known, the attribute value returned is 

VI ATTR MANF ID 

Manufacturer identification number of the VXIbus device. 


Appendix B 


385 
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Instrument Control (INSTR) Resource 


Attribute Name 

Description 


VXI and GPIB-VXI Specific INSTR Resource Attributes (continued) 


VI ATTR MEM BASE 

Base address of the device in VXIbus memory address space. 

This base address is applicable to A24 or A32 address space. 

VI ATTR MEM SIZE 

Size of memory requested by the device in VXIbus address 
space. 

VI ATTR MEM SPACE 

VXIbus address space used by the device. The three types are 
A16 only, A16/A24, or A16/A32 memory address space. 

VI ATTR MODEL CODE 

Model code for the device. 

VI ATTR SLOT 

Physical slot location of the VXIbus device. If the slot number is 
not known, vi unknown slot is returned. 

VI ATTR VXI LA 

Logical address of the VXI or VME device used by the given 
session. For a VME device, the logical address is actually a 
pseudo-address in the range 256 to 511. 

VI ATTR CMDR LA 

Logical address of the commander of the VXI device used by 
the given session. 

VI ATTR IMMEDIATE SERV 

Specifies whether the given device is an immediate servant of the 
controller running VISA. 

VI ATTR FDC CHNL 

This attribute determines which FDC channel will be used to 
transfer the buffer. 

VI ATTR FDC SIGNAL GEN EN 

Setting this attribute to vi true lets the servant send a signal 
when control of the FDC channel is passed back to the 
commander. This action frees the commander from having to 
poll the FDC header while engaging in an FDC transfer. 

VI ATTR FDC MODE 

This attribute determines which FDC mode to use (Normal mode 
or Stream mode). 

VI ATTR FDC USE PAIR 

If set to vi true, a channel pair will be used for transferring 
data. Otherwise, only one channel will be used. 

VI ATTR SRC INCREMENT 

This is used in the viMoveinXX operation to specify how much 
the source offset is to be incremented after every transfer. The 
default value of this attribute is 1 (that is, the source address will 
be incremented by 1 after each transfer), and the viMoveinXX 
operation moves from consecutive elements. 

If this attribute is set to 0, the viMoveinXX operation will always 
read from the same element, essentially treating the source as a 
FIFO register. 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 

Attribute Name 

Description 


VXI and GPIB-VXI Specific INSTR Resource Attributes (continued) 


VI ATTR DEST INCREMENT 

This is used in the viMoveOutxx operation to specify how much 
the destination offset is to be incremented after every transfer. 

The default value of this attribute is 1 (that is, the destination 
address will be incremented by 1 after each transfer), and the 
viMoveOutxx operation moves into consecutive elements. 

If this attribute is set to 0, the viMoveOutxx operation will always 
write to the same element, essentially treating the destination as a 
FIFO register. 

VI ATTR WIN ACCESS 

Modes in which the current window may be accessed: not 
currently mapped, through operations viPeekxx and 
viPokeXX only, or through operations and/or by directly 
dereferencing the address parameter as a pointer. 

VI ATTR WIN BASE ADDR 

Base address of the interface bus to which this window is 
mapped. 

VI ATTR WIN SIZE 

Size of the region mapped to this window. 

VI ATTR SRC BYTE ORDER 

This attribute specifies the byte order to be used in high-level 
access operations, such as viinxx and viMoveinXX, when 
reading from the source. 

VI ATTR DEST BYTE ORDER 

This attribute specifies the byte order to be used in high-level 
access operations, such as viOutxx and viMoveOutxx, when 
writing to the destination 

VI ATTR WIN BYTE ORDER 

This attribute specifies the byte order to be used in low-level 
access operations, such as viMapAddress, viPeekxx and 
viPokeXX, when accessing the mapped window. 

VI ATTR SRC ACCESS PRIV 

This attribute specifies the address modifier to be used in high- 
level access operations, such as viinxx and viMoveinXX, 
when reading from the source. 

VI ATTR DEST ACCESS PRIV 

This attribute specifies the address modifier to be used in high- 
level access operations, such as viOutxx and viMoveOutxx, 
when writing to the destination. 

VI ATTR WIN ACCESS PRIV 

This attribute specifies the address modifier to be used in low- 
level access operations, such as viMapAddress, viPeekxx and 
viPokeXX, when accessing the mapped window. 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 


Attribute Name 

Description 


VXI and GPIB-VXI Specific INSTR Resource Attributes (continued) 


VI ATTR VXI DEV CLASS 

This attribute represents the VXI-defined device class to which 
the resource belongs: 

■ message based (vi vxi class message) 

■ register based (vi vxi class register) 

■ extended (vi vxi class extended) 

■ memory (vi vxi class memory) 

VME devices are usually either register based or belong to a 
miscellaneous class (vi vxi class other) 

VI ATTR MANF NAME 

This string attribute is the manufacturer's name. The value of this 
attribute should be used for display purposes only and not for 
programmatic decisions, as the value can be different between 
VISA implementations and/or revisions. 

VI ATTR MODEL NAME 

This string attribute is the model name of the device. The value of 
this attribute should be used for display purposes only and not for 
programmatic decisions, as the value can be different between 
VISA implementations and/or revisions. 

VI ATTR VXI TRIG SUPPORT 

This attribute shows which VXI trigger lines this implementation 
supports. This is a bit vector with bits 0-9 corresponding to 

VI TRIG TTLO through VI TRIG ECL1. 


GPIB-VXI Specific INSTR Resource Attribute 


VI ATTR INTF PARENT NUM 

Board number of the GPIB board to which the GPIB-VXI is 
attached. 


ASRL Specific INSTR Resource Attributes 


VI ATTR ASRL AVAIL NUM 

This attribute shows the number of bytes available in the global 
receive buffer. 

VI ATTR ASRL BAUD 

This is the baud rate of the interface. It is represented as an 
unsigned 32-bit integer so that any baud rate can be used, but 
it usually requires a commonly used rate such as 300, 1200, 

2400, or 9600 baud. 

VI ATTR ASRL DATA BITS 

This is the number of data bits contained in each frame (from 5 to 
8). The data bits for each frame are located in the low-order bits of 
every byte stored in memory. 
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VISA Resource Classes 

Instrument Control (INSTR) Resource 

Attribute Name 

Description 


ASRL Specific INSTR Resource Attributes (continued) 


VI ATTR ASRL PARITY 

This is the parity used with every frame transmitted and received, 
vi asrl par mark means that the parity bit exists and is 
always 1. means that the parity bit exists 

and is always 0. 

VI ATTR ASRL STOP BITS 

This is the number of stop bits used to indicate the end of a frame. 
The value vi asrl stop ones indicates one-and-one-half 
(1.5) stop bits. 

VI ATTR ASRL FLOW CNTRL 

If this attribute is set to vi attr asrl flow none, the transfer 
mechanism does not use flow control, and buffers on both sides of 
the connection are assumed to be large enough to hold all data 
transferred. 

If this attribute is set to vi attr asrl flow xon xoff, the 
transfer mechanism uses the XON and XOFF characters to 
perform flow control. The transfer mechanism controls input flow 
by sending XOFF when the receive buffer is nearly full, and it 
controls the output flow by suspending transmission when XOFF 
is received. 

If this attribute is set to vi attr asrl flow rts cts, the 
transfer mechanism uses the RTS output signal and the CTS 
input signal to perform flow control. The transfer mechanism 
controls input flow by unasserting the RTS signal when the 
receive buffer is nearly full, and it controls output flow by 
suspending the transmission when the CTS signal is unasserted. 

If this attribute is set to vi asrl flow dtr dsr, the transfer 
mechanism uses the DTR output signal and the DSR input signal 
to perform flow control. The transfer mechanism controls input 
flow by unasserting the DTR signal when the receive buffer is 
nearly full, and it controls output flow by suspending the 
transmission when the DSR signal is unasserted. 

This attribute can specify multiple flow control mechanisms by bit- 
ORing multiple values together. However, certain combinations 
may not be supported by all serial ports and/or operating systems. 
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Instrument Control (INSTR) Resource 


Attribute Name 

Description 


ASRL Specific INSTR Resource Attributes (continued) 


VI ATTR ASRL END IN 

This attribute indicates the method used to terminate read 
operations. If it is set to vi asrl end none, the read will not 
terminate until all of the requested data is received (or an error 
occurs). 

If it is set to vi asrl end termchar, the read will terminate as 
soon as the character in vi attr termchar is received. If it is 
set to vi asrl end last bit, the read will terminate as soon 
as a character arrives with its last bit set. For example, if 
vi attr asrl data bits is set to 8, then the read will 
terminate when a character arrives with the 8th bit set. 

VI ATTR ASRL END OUT 

This attribute indicates the method used to terminate write 
operations. If it is set to vi asrl end none, the write will not 
append anything to the data being written. If it is set to 
vi asrl end break, the write will transmit a break after all the 
characters for the write have been sent. If it is set to 
vi asrl end last bit, the write will send all but the last 
character with the last bit clear, then transmit the last character 
with the last bit set. 

For example, if vi attr asrl data bits is set to 8, then 
the write will clear the 8th bit for all but the last character, then 
transmit the last character with the 8th bit set. If it is set to 
vi asrl end termchar, the write will send the character in 
vi attr termchar after the data being transmitted. 

VI ATTR ASRL CTS STATE 

This attribute shows the current state of the Clear To Send (CTS) 
input signal. 

VI ATTR ASRL DCD STATE 

This attribute shows the current state of the Data Carrier Detect 
(DCD) input signal. The DCD signal is often used by modems to 
indicate the detection of a carrier (remote modem) on the 
telephone line. The DCD signal is also known as "Receive Line 
Signal Detect (RLSD)." 

VI ATTR ASRL DSR STATE 

This attribute shows the current state of the Data Set Ready 
(DSR) input signal. 

VI ATTR ASRL DTR STATE 

This attribute is used to manually assert or unassert the Data 
Terminal Ready (DTR) output signal. 

VI ATTR ASRL RI STATE 

This attribute shows the current state of the Ring Indicator (RI) 
input signal. The RI signal is often used by modems to indicate 
that the telephone line is ringing. 
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Attribute Name 

Description 

ASRL Specific INSTR Resource Attributes (continued) 

VI ATTR ASRL RTS STATE 

This attribute is used to manually assert or unassert the 

Request To Send (RTS) output signal. When the 
vi attr asrl flow cntrl attribute is set to 
vi asrl flow rts CTS, this attribute is ignored when 
changed, but can be read to determine whether the background 
flow control is asserting or unasserting the signal. 

VI ATTR ASRL REPLACE CHAR 

This attribute specifies the character to be used to replace 
incoming characters that arrive with errors (such as parity error.) 

VI ATTR ASRL XON CHAR 

This attribute specifies the value of the XON character used for 
XON/XOFF flow control (both directions). If XON/XOFF flow 
control (software handshaking) is not being used, the value of this 
attribute is ignored. 

VI ATTR ASRL XOFF CHAR 

This attribute specifies the value of the XOFF character used for 
XON/XOFF flow control (both directions). If XON/XOFF flow 
control (software handshaking) is not being used, the value of this 
attribute is ignored. 

TCPIP Specific INSTR Resource Attributes 

VI ATTR TCPIP ADDR 

This is the TCPIP address of the device to which the session is 
connected. This string is formatted in dot-notation. 

VI ATTR TCPIP HOSTNAME 

This specifies the host name of the device. If no host name is 
available, this attribute returns an empty string. 

VI ATTR TCPIP DEVICE NAME 

This specifies the LAN device name used by the VXI-11 protocol 
during connection. 


INSTR Resource Events 

This resource defines the following events for communication with 
applications, where AP = Access Privilege. 

VI_EVENT_SERVICE_REQUEST 

Notification that a service request was received from the device.. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

SERVICE REQ 
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VI_EVENT_VXI_SIGP 

Notification that a VXIbus signal or VXIbus interrupt was received from the 
device. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

VXI STOP 

VI ATTR SIGP 

STATUS ID 

The 16-bit Status/ID value 
retrieved during the IACK 
cycle or from the Signal 
register. 

RO 

ViUIntl6 

0 to FFFF h 


VI_EVENT_TRIG 

Notification that a trigger interrupt was received from the device. For VISA, 
the only triggers that can be sensed are VXI hardware triggers on the 
assertion edge (SYNC and ON trigger protocols only). 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV 

TRIG ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed 

RO 

ViJobld 

N/A 
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Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

Oto FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 


ViString 

N/A 


VI_EVENT_VXI_VME_INTR 

Notification that a VXIbus interrupt was received from the device. NOT 

IMPLEMENTED IN AGILENT VISA. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of 
the event. 

RO 

ViEventType 

VI EVENT VXI 

VME INTR 

VI ATTR STATUS ID 

32-bit status/ID retrieved 
during the IACK cycle. 

RO 

ViUInt32 

Oto FFFFFFFF h 

VI ATTR RECV INTR 

LEVEL 

VXI interrupt level on which 
the interrupt was received. 

RO 

VIInti6 

1 to 7, 

VI UNKNOWN LEVEL 


INSTR Resource Operations 

viAssertTrigger(w, protocol) 
viBufRead ( vi, buf, count, retCount) 
viBufWrite (vi, buf, count, retCount) 
viClear (vi) 
viFlush (vi, mask) 
viGpibControlREN (vi, mode) 

vilnl6 (vi, space, offset, vail6) 
viln32 (vi, space, offset, val32) 
viln8 (vi, space, offset, val8) 

viMapAddress (vi, mapSpace, mapBase, mapSize, access, 
suggested, address) 
viMemAlloc (vi, size, offset) 
viMemFree (vi, offset) 
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viMove ( vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, 
destWidth, length) 

viMoveAsync ( vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, 
destWidth, length, job Id) 
viMoveIn8 ( vi, space, offset, length, buf8) 
viMoveInl6 (vi, space, offset, length, buf16) 
viMoveln32 (vi, space, offset, length, buf32) 

viMoveOut8 (vi, space, offset, length, buf8) 

viMoveOutl6 (vi, space, offset, length, buf16) 

viMoveOut32 (vi, space, offset, length, buf32) 

viOut8 (vi, space, offset, val8) 

viOutl6 (vi, space, offset, vail6) 

viOut32 (vi, space, offset, val32) 

viPeek.8 (vi, addr, val8) 

viPeekl6 (vi, addr, vail6) 

viPeek.32 (vi, addr, val32) 

viPoke8 (vi, addr, val8) 

viPokel6 (vi, addr, vail6) 

viPoke32 (vi, addr, val32) 

viPrintf (vi, writeFmt, argl, arg2, ...) 
viQueryf (vi, writeFmt, readFmt, argl, arg2, ...) 
viRead ( vi, buf, count, retCount) 
viReadAsync ( vi, buf, count, jobld) 
viReadSTB (vi, status) 

viReadToFile (vi, fileName, count, retCount) 
viScanf (vi, readFmt, argl, arg2, ...) 
viSetBuf (vi, mask, size) 
viSPrintf (vi, buf, writeFmt, argl, arg2, ...) 
viSScanf (vi, buf, readFmt, argl, arg2, ...) 

viUnmapAddress (vi) 
viVPrintf ( vi, writeFmt, para ms) 
viVQueryf (vi, writeFmt, readFmt, params) 
viVScanf (vi, readFmt, params) 
viVSPrintf (vi, buf, writeFmt, params) 
viVSScanf (vi, buf, readFmt, params) 
viVxiCommandQuery (vi, mode, cmd, response) 
viWrite (vi, buf, count, retCount) 
viWriteAsync (vi, buf, count, jobld) 
viWriteFromFile (vi, fileName, count, retCount) 
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Memory Access (MEMACC) Resource 

This section describes the Memory Access (MEMACC) Resource that is 
provided to encapsulate the address space of a memory-mapped bus, such 
as the VXIbus. 

MEMACC Resource Overview 

The Memory Access (MEMACC) Resource encapsulates the address space 
of a memory-mapped bus such as the VXIbus. A VISA Memory Access 
Resource, like any other resource, starts with the basic operations and 
attributes of the VISA Resource Template. For example, modifying the state 
of an attribute is done via the operation viSetAttribute. 

Although the MEMACC resource does not have viSetAttribute listed in 
its operations, it provides the operation because it is defined in the VISA 
Resource Template. From this basic set, each resource adds its specific 
operations and attributes that allow it to perform its dedicated task, such as 
reading a register or writing to a memory location. 

The MEMACC Resource lets a controller interact with the interface 
associated with this resource. It does this by providing the controller with 
services to access arbitrary registers or memory addresses on memory- 
mapped buses. 
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MEMACC Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic MEMACC Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF VXI 

VI INTF GPIB VXI 

N/A 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VI ATTR DMA ALLOW 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VXI and GPIB-VXI Specific MEMACC Resource Attributes 

VI ATTR VXI LA 

RO 

Global 

Vilntl6 

0 to 255 

N/A 

VI ATTR SRC 

INCREMENT 

RW 

Local 

Vilnt32 

Oto 1 

1 

VI ATTR DEST 

INCREMENT 

RW 

Local 

Vilnt32 

Oto 1 

1 

VI ATTR WIN ACCESS 

RO 

Local 

ViUIntl6 

VI NMAPPED 

VI USE OPERS 

VI DEREF ADDR 

VI NMAPPED 

VI ATTR WIN BASE 

ADDR 

RO 

Local 

ViBusAddr 

ess 

N/A 

N/A 

VI ATTR WIN SIZE 

RO 

Local 

ViBusSize 

N/A 

N/A 

VI ATTR SRC BYTE 

ORDER 

RW 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 

VI ATTR DEST BYTE 

ORDER 

RW 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 

VI ATTR WIN BYTE 

ORDER 

RW* 

Local 

ViUIntl6 

VI BIG ENDIAN 

VI LITTLE ENDIAN 

VI BIG 

ENDIAN 
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Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

VXI and GPIB-VXI Specific MEMACC Resource Attributes 

VI ATTR SRC 

ACCESS priv 

RW 

Local 

ViUIntl6 

VI 

VI 

VI 

VI 

VI 

VI 

VI 

VI 

DATA NPRIV 

DATA PRIV 

PROG NPRIV 

PROG PRIV 

BLCK NPRIV 

BLCK PRIV 

D64 NPRIV 

D64 PRIV 

VI DATA 

PRIV 

VI ATTR DEST 

ACCESS PRIV 

RW 

Local 

ViUIntl6 

VI 

VI 

VI 

VI 

VI 

VI 

VI 

VI 

DATA NPRIV 

-DATA PRIV 

PROG NPRIV 

PROG PRIV 

BLCK NPRIV 

BLCK PRIV 

D64 NPRIV 

D64 PRIV 

VI DATA 

PRIV 

VI ATTR WIN 

ACCESS PRIV 

RW* 

Local 

ViUIntl6 

VI 

VI 

VI 

VI 

VI 

VI 

DATA NPRIV 

-DATA PRIV 

PROG NPRIV 

PROG PRIV 

BLCK NPRIV 

BLCK PRIV 

VI DATA 

PRIV 

GPIB-VXI Specific MEMACC Resource Attributes 

VI ATTR INTF 

PARENT NUM 

RO 

Global 

ViUIntl6 

0 

to FFFF h 

N/A 

VI ATTR GPIB 

PRIMARY ADDR 

RO 

Global 

ViUIntl6 

0 

to 30 

N/A 

VI ATTR GPIB 

SECONDARY ADDR 

RO 

Global 

ViUIntl6 

0 

VI 

to 31, 

_NO_SEC_ADDR 

N/A 


* For VISA 2.2, the attributes vi_attr_win_byte_order and vi_attr_win_access_priv are RW 
(readable and writeable) when the corresponding session is not mapped (vi_attr_win_access = = 
vi_nmapped). When the session is mapped, these attributes are RO (read only). 
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MEMACC Resource Attribute Descriptions 


Attribute Name 

Description 


Generic MEMACC Resource Attributes 


VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value of 
vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 

VI ATTR DMA ALLOW EN 

This attribute specifies whether I/O accesses should use DMA 
(vi true) or Programmed I/O (vi false). In some 
implementations, this attribute may have global effects even 
though it is documented to be a local attribute. Since this affects 
performance and not functionality, that behavior is acceptable. 


VXI and GPIB-VXI Specific MEMACC Resource Attributes 


VI ATTR VXI LA 

Logical address of the local controller. 

VI ATTR SRC INCREMENT 

This is used in the viMoveinXX operation to specify how much 
the source offset is to be incremented after every transfer. The 
default value of this attribute is 1 (that is, the source address will 
be incremented by 1 after each transfer), and the viMoveinXX 
operation moves from consecutive elements. 

If this attribute is set to 0, the viMoveinXX operation will always 
read from the same element, essentially treating the source as a 
FIFO register. 

VI ATTR DEST INCREMENT 

This is used in the viMoveOutxx operation to specify how much 
the destination offset is to be incremented after every transfer. 

The default value of this attribute is 1 (that is, the destination 
address will be incremented by 1 after each transfer), and the 
viMoveOutxx operation moves into consecutive elements. 

If this attribute is set to 0, the viMoveOutxx operation will always 
write to the same element, essentially treating the destination as a 
FIFO register. 
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Attribute Name 

Description 

VXI and GPIB-VXI Specific MEMACC Resource Attributes (continued) 

VI ATTR WIN ACCESS 

Modes in which the current window may be accessed: not 
currently mapped, through operations viPeekxx and 
viPokeXX only, or through operations and/or by directly 
dereferencing the address parameter as a pointer. 

VI ATTR WIN BASE ADDR 

Base address of the interface bus to which this window is 
mapped. 

VI ATTR WIN SIZE 

Size of the region mapped to this window. 

VI ATTR SRC BYTE ORDER 

This attribute specifies the byte order to be used in high-level 
access operations, such as viinxx and viMoveinXX, when 
reading from the source. 

VI ATTR DEST BYTE ORDER 

This attribute specifies the byte order to be used in high-level 
access operations, such as viOutxx and viMoveOutxx, when 
writing to the destination. 

VI ATTR WIN BYTE ORDER 

This attribute specifies the byte order to be used in low-level 
access operations, such as viMapAddress, viPeekxx and 
viPokeXX, when accessing the mapped window. 

VI ATTR SRC ACCESS PRIV 

This attribute specifies the address modifier to be used in high- 
level access operations, such as viinxx and viMoveinXX, 
when reading from the source. 

VI ATTR DEST ACCESS PRIV 

This attribute specifies the address modifier to be used in high- 
level access operations, such as viOutxx and viMoveOutxx, 
when writing to the destination. 

VI ATTR WIN ACCESS PRIV 

This attribute specifies the address modifier to be used in low- 
level access operations, such as viMapAddress, viPeekxx and 
viPokeXX, when accessing the mapped window. 

GPIB-VXI Specific MEMACC Resource Attributes 

VI ATTR INTF PARENT NUM 

Board number of the GPIB board to which the GPIB-VXI is 
attached. 

VI ATTR GPIB PRIMARY ADDR 

Primary address of the GPIB-VXI controller used by the given 
session. 

VI ATTR GPIB SECONDARY ADDR 

Secondary address of the GPIB-VXI controller used by the given 
session. 
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MEMACC Resource Events 

This resource defines the following event for communication with 
applications, where AP = Access Privilege. 

VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 

10 COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed. 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed. 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements that 
were asynchronously 
transferred. 

RO 

ViUInt32 

Oto FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 

RO 

ViString 

N/A 
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MEMACC Resource Operations 

viln8 ( vi, space, offset, val8) 
vilnl6 ( vi, space, offset, vail6) 
viln32 ( vi, space, offset, val32) 

viMapAddress ( vi, mapSpace, mapBase, mapSize, access, suggested, 
address) 

viMove ( vi, srcSpace, srcOffset, srcWidth, destSpace, 
destOffset, destWidth, length) 

viMoveAsync ( vi, srcSpace, srcOffset, srcWidth, destSpace, destOffset, 
destWidth, length, job Id) 

viMoveIn8 ( vi, space, offset, length, buf8) 
viMoveInl 6 ( vi, space, offset, length, buf16) 
viMoveln32 ( vi, space, offset, length, buf32) 
viMoveOut8 (vi, space, offset, length, buf8) 
viMoveOutl6 (vi, space, offset, length, buf16) 
viMoveOut32 (vi, space, offset, length, buf32) 

viOut8 (vi, space, offset, val8) 
viOutl6 (vi, space, offset, vail6) 
viOut32 (vi, space, offset, val32) 
viPeek.8 (vi, addr, val8) 
viPeekl6 (vi, addr, vail6) 
viPeek32 (vi, addr, val32) 
viPoke8 ( vi, addr, val8) 
vi Poke 16 (vi, addr, vail 6) 
viPoke32 (vi, addr, val32) 
viUnmapAddress (vi) 
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GPIB Bus Interface (INTFC) Resource 

This section describes the GPIB Bus Interface (INTFC) Resource that is 
provided to encapsulate the operations and properties of a raw GPIB 
interface (reading, writing, triggering, etc.). 

INTFC Resource Overview 

A VISA GPIB Bus Interface (INTFC) Resource, like any other resource, 
defines the basic operations and attributes of the VISA Resource Template. 

For example, modifying the state of an attribute is done via the operation 
viSetAttribute. Although the INTFC resource does not have 
viSetAttribute listed in its operations, it provides the operation 
because it is defined in the VISA Resource Template. From this basic set, 
each resource adds its specific operations and attributes that allow it to 
perform its dedicated task. 

The INTFC Resource lets a controller interact with any devices connected 
to the board associated with this resource. Services are provided to send 
blocks of data onto the bus, request blocks of data from the bus, trigger 
devices on the bus, and send miscellaneous commands to any or all 
devices. In addition, the controller can directly query and manipulate specific 
lines on the bus and also pass control to other devices with controller 
capability. 

INTFC Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic INTFC Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF GPIB 

VI INTF 

GPIB 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR SEND END 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI TRUE 
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Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic INTFC Resource Attributes (continued) 

VI ATTR TERMCHAR 

RW 

Local 

ViUInt8 

0 to FF(-j 

0A h (linefeed) 

VI ATTR TERMCHAR 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VI ATTR DEV STATUS 

BYTE 

RW 

Global 

ViUInt8 

0 to FF(-| 

N/A 

VI ATTR WR BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH WHEN FULL 

VI FLUSH 

WHEN FULL 

VI ATTR DMA ALLOW 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR RD BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH DISABLE 

VI FLUSH 

DISABLE 

VI ATTR FILE 

APPEND EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

GPIB Specific INTFC Resource Attributes 

VI ATTR GPIB 

PRIMARY ADDR 

RW 

Global 

ViUIntl6 

Oto 30 

N/A 

VI ATTR GPIB 

SECONDARY ADDR 

RW 

Global 

ViUIntl6 

Oto 31, 

VI NO SEC ADDR 

VI NO SEC 

ADDR 

VI ATTR GPIB REN 

STATE 

RO 

Global 

Vilntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR GPIB ATN 

STATE 

RO 

Global 

Vilntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR GPIB NDAC 

STATE 

RO 

Global 

Vilntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 
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Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

GPIB Specific INTFC Resource Attributes (continued) 

VI ATTR GPIB SRQ 

STATE 

RO 

Global 

Vilntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR GPIB CIC 

STATE 

RO 

Global 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR GPIB SYS 

CNTRL STATE 

RW 

Global 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR GPIB 

HS488 CBL LEN 

RW 

Global 

Vilntl6 

1 to 15, 

VI GPIB HS488 

DISABLED, 

VI GPIB HS488 NIMPL 

N/A 

VI ATTR GPIB 

ADDR STATE 

RO 

Global 

Vilntl6 

VI GPIB UNADDRESSED 

VI GPIB TALKER 

VI GPIB LISTENER 

N/A 


INTFC Resource Attribute Descriptions 


Attribute Name 

Description 

Generic INTFC Resource Attributes 

VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR SEND END EN 

Whether to assert END during the transfer of the last byte 
of the buffer. 

VI ATTR TERMCHAR 

Termination character. When the termination character is read 
and vi attr termchar en is enabled during a read 
operation, the read operation terminates 

VI ATTR TERMCHAR EN 

Flag that determines whether the read operation should terminate 
when a termination character is received. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value of 
vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 
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Attribute Name 

Description 


Generic INTFC Resource Attributes (continued) 


VI ATTR DEV STATUS BYTE 

This attribute specifies the 488-style status byte of the local 
controller associated with this session. If this attribute is 
written and bit 6 (0x40) is set, this device or controller will 
assert a service request (SRQ) if it is defined for this interface. 

VI ATTR WR BUF OPER MODE 

Determines the operational mode of the write buffer. When the 
operational mode is set to vi flush when full (default), the 
buffer is flushed when an END indicator is written to the buffer, or 
when the buffer fills up. 

If the operational mode is set to vi flush on access, the 
write buffer is flushed under the same conditions, and also 
every time a viPrintf operation completes. 

VI ATTR DMA ALLOW EN 

This attribute specifies whether I/O accesses should use 

DMA (vi true) or Programmed I/O (vi false). In some 
implementations, this attribute may have global effects even 
though it is documented to be a local attribute. Since this affects 
performance and not functionality, that behavior is acceptable. 

VI ATTR RD BUF OPER MODE 

Determines the operational mode of the read buffer. When the 
operational mode is set to vi flush disable (default), the 
buffer is flushed only on explicit calls to viFlush. If the 
operational mode is set to vi flush on access, the buffer 
is flushed every time a viScanf operation completes. 

VI ATTR FILE APPEND EN 

This attribute specifies whether viReadToFile will overwrite 
(truncate) or append when opening a file. 


GPIB Specific INTFC Resource Attributes 


VI ATTR GPIB PRIMARY ADDR 

Primary address of the local GPIB controller used by the given 
session. 

VI ATTR GPIB SECONDARY ADDR 

Secondary address of the local GPIB controller used by the given 
session. 

VI ATTR GPIB REN STATE 

This attribute returns the current state of the GPIB REN 
(Remote ENable) interface line. 

VI ATTR GPIB ATN STATE 

This attribute shows the current state of the GPIB ATN 
(ATtentioN) interface line. 

VI ATTR GPIB NDAC STATE 

This attribute shows the current state of the GPIB NDAC 
(Not Data Accepted) interface line. 
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VISA Resource Classes 

GPIB Bus Interface (INTFC) Resource 


Attribute Name 

Description 

GPIB Specific INTFC Resource Attributes (continued) 

VI ATTR GPIB SRQ STATE 

This attribute shows the current state of the GPIB SRQ (Service 
ReQuest) interface line. 

VI ATTR GPIB CIC STATE 

This attribute shows whether the specified GPIB interface is 
currently CIC (controller in charge). 

VI ATTR GPIB SYS CNTRL STATE 

This attribute shows whether the specified GPIB interface is 
currently the system controller. In some implementations, this 
attribute may be modified only through a configuration utility. 

On these systems, this attribute is read only (RO). 

VI ATTR GPIB HS488 CBL LEN 

This attribute specifies the total number of meters of GPIB cable 
used in the specified GPIB interface. If HS488 is not 
implemented, querying this attribute should return the value 
vi gpib HS488 NIMPL. On these systems, trying to set this 
attribute value will return error vi error nsup attr state. 

VI ATTR GPIB ADDR STATE 

This attribute shows whether the specified GPIB interface is 
currently addressed to talk or listen, or is not addressed. 


INTFC Resource Events 

This resource defines the following events for communication with 
applications, where AP = Access Privilege. 


VI_EVENT_GPIB_CIC 

Notification that the GPIB controller has gained or lost CIC (controller in 
charge) status. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

CIC 

VI ATTR GPIB RECV 

CIC STATE 

Controller has become 
controller in charge. 

RO 

ViBoolean 

VI TRUE 

VI FALSE 
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VISA Resource Classes 

GPIB Bus Interface (INTFC) Resource 


VI_E VE NT_G PI B_TALK 

Notification that the GPIB controller has been addressed to talk. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

TALK 


VI_EVENT_GPIB_LISTEN 

Notification that the GPIB controller has been addressed to listen. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

LISTEN 


VI_EVENT_CLEAR 

Notification that the GPIB controller has been sent a device clear message. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT CLEAR 


VI_EVENT_TRIGGER 

Notification that a trigger interrupt was received from the interface. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG SW 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 
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VISA Resource Classes 

GPIB Bus Interface (INTFC) Resource 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed. 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed. 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of buffer used in an 
asynchronous operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

0 to FFFFFFFF h 

VI ATTR OPER NAME 

The name of the operation 
generating the event. 

RO 

ViString 

N/A 


INTFC Resource Operations 

viAssertTrigger ( vi, protocol) 
viBufRead ( vi, buf, count, retCount) 
viBufWrite (vi, buf, count, retCount) 
viFlush (vi, mask) 

viGpibCommand ( vi, buf, count, retCount) 
viGpibControlATN {vi, mode) 
viGpibControlREN (vi, mode) 
viGpibPassControl (vi, primAddr, secAddr) 
viGpibSendIFC ( vi) 
viPrintf (vi, writeFmt, argl, arg2, ...) 
viRead (vi, buf, count, retCount) 
viReadAsync (vi, buf, count, jobld) 
viReadToFile (vi, fileName, count, retCount) 
viScanf (vi, readFmt, argl, arg2, ...) 
viSetBuf (vi, mask, size) 
viSPrintf ( vi, buf, writeFmt, argl, arg2, ...) 
viSScanf (vi, buf, readFmt, argl, arg2, ...) 
viVPrintf (vi, writeFmt, para ms) 
viVScanf (vi, readFmt, params) 
viVSPrintf (vi, buf, writeFmt, params) 
viVSScanf (vi, buf, readFmt, params) 
vi Write (vi, buf, count, retCount) 
viWriteAsync ( vi, buf, count, jobld) 
viWriteFromFile (vi, fileName, count, retCount) 
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VXI Mainframe Backplane (BACKPLANE) Resource 


VXI Mainframe Backplane (BACKPLANE) 
Resource 

This section describes the VXI Mainframe Backplane (BACKPLANE) 
Resource that encapsulates the VXI-defined operations and properties of 
the backplane in a VXIbus system. 

BACKPLANE Resource Overview 

A VISA VXI Mainframe Backplane Resource, like any other resource, starts 
with the basic operations and attributes of the VISA Resource Template. 

For example, modifying the state of an attribute is done via the operation 
viSetAttribute, which is defined in the VISA Resource Template. 

Although the BACKPLANE resource does not have viSetAttribute 
listed in its operations, it provides the operation because it is defined in the 
VISA Resource Template. From this basic set, each resource adds its 
specific operations and attributes that allow it to perform its dedicated task. 

The BACKPLANE Resource lets a controller query and manipulate specific 
lines on a specific mainframe in a given VXI system. Services are provided 
to map, unmap, assert, and receive hardware triggers, and also to assert 
various utility and interrupt signals. This includes advanced functionality that 
may not be available in all implementations or all vendors' controllers. 

A VXI system with an embedded CPU with one mainframe will always have 
exactly one BACKPLANE resource. Valid examples of resource strings for 
this are VXIO : : 0 : : BACKPLANE and VXI : : BACKPLANE. A multi-chassis 
VXI system may provide only one BACKPLANE resource total, but the 
recommended way is to provide one BACKPLANE resource per chassis, 
with the resource string address corresponding to the attribute 
vi_attr_mainframe_la. If a multi-chassis VXI system provides only one 
BACKPLANE resource, it is assumed to control the backplane resources in 
all chasses. 


NOTE 

Some VXI or GPIB-VXI implementations view all chasses in a VXI system 
as one entity. In these configurations, separate BACKPLANE resources 
are not possible. 
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VXI Mainframe Backplane (BACKPLANE) Resource 


BACKPLANE Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic BACKPLANE Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF VXI 

VI INTF GPIB VXI 

N/A 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VXI and GPIB-VXI Specific BACKPLANE Resource Attributes 

VI ATTR TRIG ID 

RW 

Local 

Vilntl6 

VI TRIG TTLO to 

VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 

N/A 

VI ATTR MAINFRAME 

LA 

RO 

Global 

Vilntl6 

0 to 255 

VI UNKNOWN LA 

N/A 

VI ATTR VXI VME 

SYSFAIL STATE 

RO 

Global 

Vilntl6 

VI STATE ASSERTED 

VI STATE UNASSERTED 

VI STATE UNKNOWN 

N/A 

VI ATTR VXI VME 

INTR STATUS 

RO 

Global 

ViUIntl6 

N/A 

N/A 

VI ATTR VXI TRIG 

STATUS 

RO 

Global 

ViUInt32 

N/A 

N/A 

VI ATTR VXI TRIG 

SUPPORT 

RO 

Global 

ViUInt32 

N/A 

N/A 
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VISA Resource Classes 

VXI Mainframe Backplane (BACKPLANE) Resource 


BACKPLANE Resource Attribute Descriptions 


Attribute Name 

Description 


Generic BACKPLANE Resource Attributes 


VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value 
of vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 


VXI and GPIB-VXI Specific BACKPLANE Resource Attributes 


VI ATTR TRIG ID 

Identifier for the current triggering mechanism. 

VI ATTR MAINFRAME LA 

This is the logical address of a given device in the mainframe, 
usually the device with the lowest logical address. Other possible 
values include the logical address of the Slot 0 controller or of the 
parent-side extender. Often, these are 
all the same value. 

The purpose of this attribute is to provide a unique ID for each 
mainframe. A VISA manufacturer can choose any of these values, 
but must be consistent across mainframes. If this value is not 
known, the attribute value returned is vi unknown la. 

VI ATTR VXI VME SYSFAIL 

STATE 

This attribute shows the current state of the VXI/VME SYSFAIL 
(SYStem FAILure) backplane line. 

VI ATTR VXI VME INTR STATUS 

This attribute shows the current state of the VXI/VME interrupt 
lines. This is a bit vector with bits 0-6 corresponding to interrupt 
lines 1-7. 

VI ATTR VXI TRIG STATUS 

This attribute shows the current state of the VXI trigger lines. This 
is a bit vector with bits 0-9 corresponding to vi trig ttlo 
through vi trig ecli. 

VI ATTR VXI TRIG SUPPORT 

This attribute shows which VXI trigger lines this implementation 
supports. This is a bit vector with bits 0-9 corresponding to 
vi trig ttlo through VI TRIG ECLI. 

Agilent VISA also returns 12 to indicate vi trig panel in for 
received triggers and vi trig panel out for asserted triggers 
on Agilent VXI controllers. 
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VXI Mainframe Backplane (BACKPLANE) Resource 


BACKPLANE Resource Events 

This resource defines the following events for communication with 
applications, where AP = Access Privilege. 


VI_EVENT_TRIG 

Notification that a trigger interrupt was received from the backplane. For 
VISA, the only triggers that can be sensed are VXI hardware triggers on the 
assertion edge (SYNC and ON trigger protocols only). 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG TTLO to 
VI TRIG TTL7; 

VI TRIG ECLO to 

VI TRIG ECL1 


VI_EVENT_VXI_VME_SYSFAIL 

Notification that the VXI/VME SYSFAIL* line has been asserted. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT VXI 

VME SYSFAIL 


VI_EVENT_VXI_VME_SYSRESET 

Notification that the VXI/VME SYSRESET* line has been reset. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT VXI 

VME SYSRESET 


BACKPLANE Resource Operations 

viAssertTrigger(w, protocol) 
viMapTrigger(w, trigSrc, trigDest, mode) 
villnmapTrigger(w, trigSrc, trigDest) 
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Servant Device-Side (SERVANT) Resource 


Servant Device-Side (SERVANT) Resource 

This section describes the Servant Device-Side (SERVANT) Resource that 
encapsulates the operations and properties of the capabilities of a device 
and a device's view of the system in which it exists. 


NOTE 

The SERVANT Resource is not implemented in Agilent VISA. 

The SERVANT resource is a class for advanced users who want to write 
firmware code that exports device functionality across multiple interfaces. 
Most VISA users will not need this level of functionality and should not 
use the SERVANT resource in their applications. 

A VISA user of the TCPIP SERVANT resource should be aware that each 
VISA session corresponds to a unique socket connection. If the user 
opens only one SERVANT session, this precludes multiple clients from 
accessing the device. 


SERVANT Resource Overview 

A VISA Servant Resource, like any other resource, starts with the basic 
operations and attributes of the VISA Resource Template. For example, 
modifying the state of an attribute is done via the operation 
viSetAttribute, which is defined in the VISA Resource Template. 

Although the SERVANT resource does not have viSetAttribute listed in 
its operations, it provides the operation because it is defined in the VISA 
Resource Template. From this basic set, each resource adds its specific 
operations and attributes that allow it to perform its dedicated task. 

The SERVANT Resource exposes the device-side functionality of the device 
associated with this resource. Services are provided to receive blocks of 
data from a commander and respond with blocks of data in return, setting a 
488-style status byte, and receiving device clear and trigger events. 
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Servant Device-Side (SERVANT) Resource 


SERVANT Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic SERVANT Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF VXI 

VI INTF GPIB 

VI INTF TCPIP 

N/A 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR SEND END 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI TRUE 

VI ATTR TERMCHAR 

RW 

Local 

ViUInt8 

0 to FF|-| 

0A h (linefeed) 

VI ATTR TERMCHAR 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VI ATTR DEV STATUS 

BYTE 

RW 

Local 

Vilntl6 

0 to FF^ 

N/A 

VI ATTR WR BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH WHEN FULL 

VI FLUSH 

WHEN FULL 

VI ATTR DMA ALLOW 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

N/A 

VI ATTR RD BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH DISABLE 

VI FLUSH 

DISABLE 

VI ATTR FILE 

APPEND EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

GPIB Specific SERVANT Resource Attributes 

VI ATTR GPIB 

PRIMARY ADDR 

RO 

Global 

ViUIntl6 

Oto 30 

N/A 

VI ATTR GPIB 

SECONDARY ADDR 

RO 

Global 

ViUIntl6 

Oto 31 

VI NO SEC ADDR 

VI NO 

SEC ADDR 
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VISA Resource Classes 

Servant Device-Side (SERVANT) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

GPIB Specific SERVANT Resource Attributes (continued) 

VI ATTR GPIB REN 

STATE 

RO 

Global 

ViUIntl6 

VI STATE UNKNOWN 

VI STATE ASSERTED 

VI STATE UNASSERTED 

N/A 

VI ATTR GPIB ADDR 

STATE 

RO 

Global 

ViUIntl6 

VI GPIB UNADDRESSED 

VI GPIB TALKER 

VI GPIB LISTENER 

N/A 

VXI Specific SERVANT Resource Attributes 

VI ATTR VXI LA 

RO 

Global 

ViUIntl6 

Oto 511 

N/A 

VI ATTR CMDR LA 

RO 

Global 

ViUIntl6 

0 to 255, 

VI UNKNOWN LA 

N/A 

TCPIP Specific SERVANT Resource Attributes 

VI ATTR TCPIP 

DEVICE NAME 

RO 

Global 

ViString 

N/A 

N/A 


SERVANT Resource Attribute Descriptions 


Attribute Name 

Description 

Generic SERVANT Resource Attributes 

VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR SEND END EN 

Whether to assert END during the transfer of the last byte of the 
buffer. 

VI ATTR TERMCHAR 

Termination character. When the termination character is read 
and vi attr termchar en is enabled during a read 
operation, the read operation terminates. 

VI ATTR TERMCHAR EN 

Flag that determines whether the read operation should terminate 
when a termination character is received. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value 
of vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 
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VISA Resource Classes 

Servant Device-Side (SERVANT) Resource 


Attribute Name 

Description 

Generic SERVANT Resource Attributes (continued) 

VI ATTR DEV STATUS BYTE 

This attribute specifies the 488-style status byte of the local 
controller associated with this session. 

VI ATTR WR BUF OPER MODE 

Determines the operational mode of the write buffer. When the 
operational mode is set to vi flush when full (default), the 
buffer is flushed when an END indicator is written to the buffer 
or when the buffer fills up. 

If the operational mode is set to vi flush on access, the 
write buffer is flushed under the same conditions, and also every 
time a viPrintf operation completes. 

VI ATTR DMA ALLOW EN 

This attribute specifies whether I/O accesses should use 

DMA (vi true) or Programmed I/O (vi false). In some 
implementations, this attribute may have global effects even 
though it is documented to be a local attribute. Since this affects 
performance and not functionality, that behavior is acceptable. 

VI ATTR RD BUF OPER MODE 

Determines the operational mode of the read buffer. When the 
operational mode is set to vi flush disable (default), the 
buffer is flushed only on explicit calls to viFlush. 

VI ATTR FILE APPEND EN 

This attribute specifies whether viReadToFile will overwrite 
(truncate) or append when opening a file. 

GPIB Specific SERVANT Resource Attributes 

VI ATTR GPIB PRIMARY ADDR 

Primary address of local GPIB controller used by given session. 

VI ATTR GPIB SECONDARY ADDR 

Secondary address of the local GPIB controller used by the given 
session. 

VI ATTR GPIB REN STATE 

Returns the current state of the GPIB REN (Remote ENable) 
interface line. 

VI ATTR GPIB ADDR STATE 

Shows whether the specified GPIB interface is currently 
addressed to talk to listen, or to not addressed. 

VXI Specific SERVANT Resource Attributes 

VI ATTR VXI LA 

Logical address of the VXI or VME device used by the given 
session. For a VME device, the logical address is actually a 
pseudo-address in the range 256 to 511. 

VI ATTR CMDR LA 

Logical address of the commander of the VXI device used by 
the given session. 
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VISA Resource Classes 

Servant Device-Side (SERVANT) Resource 


Attribute Name 

Description 

TCPIP Specific SERVANT Resource Attributes 

VI ATTR TCPIP DEVICE NAME 

Specifies the LAN device name used by the VXI-11 protocol 
during connection. 


SERVANT Resource Events 

This resource defines the following events for communication with 
applications, where AP = Access Privilege. 


VI_EVENT_CLEAR 

Notification that the local controller has been sent a device clear message. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT CLEAR 


VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed 

RO 

ViJobld 

N/A 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

Oto FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 

RO 

ViString 

N/A 
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Servant Device-Side (SERVANT) Resource 

VI_E VE NT_G PI B_TALK 

Notification that the GPIB controller has been addressed to talk. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

TALK 


VI_EVENT_GPIB_LISTEN 

Notification that the GPIB controller has been addressed to listen. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT GPIB 

LISTEN 


VI_EVENT_TRIG 

Notification that the local controller has been triggered. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TRIG 

VI ATTR RECV TRIG 

ID 

The identifier of the triggering 
mechanism on which the 
specified trigger event was 
received. 

RO 

Vilntl6 

VI TRIG SW 


VI_EVENT_VXI_VME_SYSRESET 

Notification that the VXI/VME SYSRESET* line has been reset. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT VXI 

VME SYSRESET 


VI_EVENT_TCPIP_CONNECT 

Notification that a TCPIP connection has been made. 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT 

TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT TCPIP 

CONNECT 
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VISA Resource Classes 

Servant Device-Side (SERVANT) Resource 


Event Attribute 

Description 

AP 

Data Type 

Range 

VI ATTR RECV 

TCPIP ADDR 

The TCPIP address of the 
device from which the session 
received a connection. 

RO 

ViString 

N/A 


SERVANT Resource Operations 

viBufRead ( vi, buf, count, retCount) 
viBufWrite (vi, buf, count, retCount) 
viFlush ( vi, mask) 
viPrintf (vi, writeFmt, argl, arg2, ...) 
viRead (vi, buf, count, retCount) 

viReadAsync ( vi, buf, count, jobld) 
viReadToFile (vi, fileName, count, retCount) 
viScanf (vi, readFmt, argl, arg2, ...) 
viSetBuf (vi, mask, size) 
viSPrintf (vi, buf, writeFmt, argl, arg2, ...) 

viSScanf (vi, buf, readFmt, argl, arg2,...) 
viVPrintf ( vi, writeFmt, params) 
viVScanf ( vi, readFmt, params) 
viVSPrintf ( vi, buf, writeFmt, params) 
viVSScanf ( vi, buf, readFmt, params) 

viWrite (vi, buf, count, retCount) 
viWriteAsync ( vi, buf, count, jobld) 
viWriteFromFile (vi, fileName, count, retCount) 
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TCPIP Socket (SOCKET) Resource 

This section describes the TCPIP Socket (SOCKET) Resource that 
encapsulates the operations and properties of the capabilities of a raw 
network socket connection using TCPIP. 

SOCKET Resource Overview 

A VISA SOCKET Resource, like any other resource, starts with the basic 
operations and attributes of the VISA Resource Template. For example, 
modifying the state of an attribute is done via the operation 
viSetAttribute, which is defined in the VISA Resource Template. 

Although the TCPIP resource does not have viSetAttribute listed in 
its operations, it provides the operation because it is defined in the VISA 
Resource Template. From this basic set, each resource adds its specific 
operations and attributes that allow it to perform its dedicated task. 

The SOCKET Resource exposes the capability of a raw network socket 
connection over TCPIP. This ususally means Ethernet, but the protocol is 
not restricted to that physical interface. Services are provided to send and 
receive blocks of data. If the device is capable of communicating with 
488.2-style strings, an attribute setting also allows sending software triggers, 
querying a 488-style status byte, and sending a device clear message. 

SOCKET Resource Attributes 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic SOCKET Resource Attributes 

VI ATTR INTF NUM 

RO 

Global 

ViUIntl6 

Oto FFFF h 

0 

VI ATTR INTF TYPE 

RO 

Global 

ViUIntl6 

VI INTF TCPIP 

VI INTF 

TCPIP 

VI ATTR INTF INST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR SEND END 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI TRUE 
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TCPIP Socket (SOCKET) Resource 


Attribute Name 

Access 

Privilege 

Data Type 

Range 

Default 

Generic SOCKET Resource Attributes (continued) 

VI ATTR TERMCHAR 

RW 

Local 

ViUInt8 

0 to FF h 

0A h 

(linefeed) 

VI ATTR TERMCHAR 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR TMO VALUE 

RW 

Local 

ViUInt32 

VI TMO IMMEDIATE 

1 to FFFFFFFE h 

VI TMO INFINITE 

2000 msec 

VI ATTR WR BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH WHEN FULL 

VI FLUSH 

WHEN FULL 

VI ATTR DMA ALLOW 

EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR RD BUF 

OPER MODE 

RW 

Local 

ViUIntl6 

VI FLUSH ON ACCESS 

VI FLUSH DISABLE 

VI FLUSH 

DISABLE 

VI ATTR FILE 

APPEND EN 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 

VI ATTR 10 PROT 

RW 

Local 

ViUIntl6 

VI NORMAL 

VI PROT 4882 STRS 

VI NORMAL 

TCPIP Specific SOCKET Resource Attributes 

VI ATTR TCPIP ADDR 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR TCPIP HOST 

NAME 

RO 

Global 

ViString 

N/A 

N/A 

VI ATTR TCPIP PORT 

RO 

Global 

ViUIntl6 

Oto FFFF h 

N/A 

VI ATTR TCPIP NODE 

LAY 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI TRUE 

VI ATTR TCPIP KEEP 

ALIVE 

RW 

Local 

ViBoolean 

VI TRUE 

VI FALSE 

VI FALSE 


Appendix B 


421 

































VISA Resource Classes 

TCPIP Socket (SOCKET) Resource 


SOCKET Resource Attribute Descriptions 


Attribute Name 

Description 


Generic SOCKET Resource Attributes 


VI ATTR INTF NUM 

Board number for the given interface. 

VI ATTR INTF TYPE 

Interface type of the given session. 

VI ATTR INTF INST NAME 

Human-readable text describing the given interface. 

VI ATTR SEND END EN 

Whether to assert END during the transfer of the last byte of the 
buffer. 

VI ATTR TERMCHAR 

Termination character. When the termination character is read 
and vi attr termchar en is enabled during a read 
operation, the read operation terminates. 

VI ATTR TERMCHAR EN 

Flag that determines whether the read operation should terminate 
when a termination character is received. 

VI ATTR TMO VALUE 

Minimum timeout value to use, in milliseconds. A timeout value 
of vi tmo immediate means that operations should never wait 
for the device to respond. A timeout value of vi tmo infinite 
disables the timeout mechanism. 

VI ATTR WR BUF OPER MODE 

Determines the operational mode of the write buffer. When the 
operational mode is set to vi flush when full (default), the 
buffer is flushed when an END indicator is written to the buffer 
or when the buffer fills up. 

If the operational mode is set to vi flush on access, the 
write buffer is flushed under the same conditions, and also every 
time a viPrintf operation completes. 

VI ATTR DMA ALLOW EN 

This attribute specifies whether I/O accesses should use 

DMA (vi true) or Programmed I/O (vi false). In some 
implementations, this attribute may have global effects even 
though it is documented to be a local attribute. Since this affects 
performance and not functionality, that behavior is acceptable. 

VI ATTR RD BUF OPER MODE 

Determines the operational mode of the read buffer. When the 
operational mode is set to vi flush disable (default), the 
buffer is flushed only on explicit calls to viFlush. 

VI ATTR FILE APPEND EN 

This attribute specifies whether viReadToFile will overwrite 
(truncate) or append when opening a file. 

VI ATTR 10 PROT 

Specifies which protocol to use. 
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VISA Resource Classes 

TCPIP Socket (SOCKET) Resource 


Attribute Name 

Description 

TCPIP SOCKET Resource Attributes 

VI ATTR TCPIP ADDR 

This is the TCPIP address of the device to which the session is 
connected. This string is formatted in dot notation. 

VI ATTR TCPIP HOSTNAME 

Specifies the host name of the device. If no host name is 
available, this attribute returns an empty string. 

VI ATTR TCPIP PORT 

Specifies the port number for a given TCPIP address. For a 
TCPIP SOCKET resource, this is a required part of the address 
string. 

VI ATTR TCPIP NODELAY 

The Nagle algorithm is disabled when this attribute is enabled 
(and vice versa). The Nagle algorithm improves network 
performance by buffering "send" data until a full-size packet can 
be sent. This attribute is enabled by default in VISA to verify that 
synchronous writes get flushed immediately. 

VI ATTR TCPIP KEEPALIVE 

An application can request that a TCPIP provider enable the use 
of "keep-alive" packets on TCP connections by turning on this 
attribute. If a connection is dropped as a result of "keep-alives," 
the error code vi error conn lost is returned to current and 
subsequent I/O calls on the session. 


SOCKET Resource Event 

This resource defines the following events for communication with 
applications, where AP = Access Privilege. 

VI_EVENT_IO_COMPLETION 

Notification that an asynchronous operation has completed. 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR EVENT TYPE 

Unique logical identifier of the 
event. 

RO 

ViEventType 

VI EVENT 10 

COMPLETION 

VI ATTR STATUS 

Return code of the asynch¬ 
ronous I/O operation that has 
completed 

RO 

ViStatus 

N/A 

VI ATTR JOB ID 

Job ID of the asynchronous 
operation that has completed 

RO 

ViJobld 

N/A 
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VISA Resource Classes 

TCPIP Socket (SOCKET) Resource 


Event Attributes 

Description 

AP 

Data Type 

Range 

VI ATTR BUFFER 

Address of a buffer that was 
used in an asynchronous 
operation. 

RO 

ViBuf 

N/A 

VI ATTR RET COUNT 

Actual number of elements 
that were asynchronously 
transferred. 

RO 

ViUInt32 

Oto FFFFFFFF h 

VI ATTR OPER NAME 

Name of the operation 
generating the event. 

RO 

ViString 

N/A 


SOCKET Resource Operations 

viAssertTrigger ( vi, protocol) 
viBufRead ( vi, buf, count, retCount) 
viBufWrite (vi, buf, count, retCount) 
viClear (vi) 
viFlush (vi, mask) 

viPrintf (vi, writeFmt, argl, arg2, ...) 
viRead ( vi, buf, count, retCount) 
viReadAsync (vi, buf, count, jobld) 
viReadSTB (vi, status) 

viReadToFile (vi, filename, count, retCount) 

viScanf ( vi, readFmt, argl, arg2, ...) 
viSetBuf ( vi, mask, size) 
viSPrintf (vi, buf, writeFmt, argl, arg2, ...) 
viSScanf (vi, buf, readFmt, argl, arg2, ...) 
viVPrintf ( vi, writeFmt, params) 

viVScanf ( vi, readFmt, params) 
viVSPrintf ( vi, buf, writeFmt, params) 
viVSScanf ( vi, buf, readFmt, params) 
viWrite (vi, buf, count, retCount) 
viWriteAsync ( vi, buf, count, jobld) 
viWriteFromFile (vi, filename, count, retCount) 
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address 

A string (or other language construct) that uniquely locates and identifies 
a resource. VISA defines an ASCII-based grammar that associates 
strings with particular physical devices or interfaces and VISA resources. 

ADE 

Application Development Environment 

API 

Application Programmers Interface. The direct interface that an end user 
sees when creating an application. The VISA API consists of the sum of 
all of the operations, attributes, and events of each of the VISA Resource 
Classes. 

attribute 

A value within a resource that reflects a characteristic of the operational 
state of a resource. The operational state of some attributes can be 
changed. 

bus error 

An error that signals failed access to an address. Bus errors occur with 
low-level accesses to memory and usually involve hardware with bus 
mapping capabilities. For example, non-existent memory, a non-existent 
register, or an incorrect device access can cause a bus error. 

commander 

A device that has the ability to control another device. This term can also 
denote the unique device that has sole control over another device (as 
with the VXI Commander/Servant hierarchy). 

communication channel 

The same as Session. A communication path between a software 
element and a resource. Every communication channel in VISA is 
unique. 
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controller 

A device, such as a computer, used to communicate with a remote 
device, such as an instrument. In the communications between the 
controller and the device, the controller is in charge of and controls the 
flow of communication (that is, the controller does the addressing 
and/or other bus management). 

device 

An entity that receives commands from a controller. A device can be an 
instrument, a computer (acting in a non-controller role), or a peripheral 
(such as a plotter or printer). In VISA, the concept of a device is generally 
the logical association of several VISA resources. 

device driver 

A segment of software code that communicates with a device. It may 
either communicate directly with a device by reading to and writing from 
registers, or it may communicate through an interface driver. 

device session 

A session that communicates as a controller specifically with a single 
device, such as an instrument. 

handler 

A software routine used to respond to an asynchronous event such as an 
SRQ or an interrupt. 

instrument 

A device that accepts some form of stimulus to perform a designated 
task, test, or measurement function. Two common forms of stimuli are 
message passing and register reads and writes. Other forms include 
triggering or varying forms of asynchronous control. 

instrument driver 

Library of functions for controlling a specific instrument. 

interface 

A generic term that applies to the connection between devices and 
controllers. It includes the communication media and the device/ 
controller hardware necessary for cross-communication. 
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interrupt 

An asynchronous event requiring attention out of the normal flow of 
control of a program. 

mapping 

An operation that returns a reference to a specified section of an address 
space and makes the specified range of addresses accessible to the 
requester. This function is independent of memory allocation. 

operation 

An action defined by a resource that can be performed on a resource. 

process 

An operating system component that shares a system's resources. A 
multi-process system is a computer system that allows multiple programs 
to execute simultaneously, each in a separate process environment. A 
single-process system is a computer system that allows only a single 
program to execute at a given point in time. 

register 

An address location that either contains a value that is a function of the 
state of hardware or can be written into to cause hardware to perform a 
particular action or to enter a particular state. In other words, an address 
location that controls and/or monitors hardware. 

resource (or resource instance) 

An instrument while using VISA. In general, this term is synonymous with 
the connotation of the word object in object-oriented architectures. For 
VISA, resource more specifically refers to a particular implementation (or 
instance in object-oriented terms) of a Resource Class. In VISA, every 
defined software module is a resource. 

resource class 

The definition for how to create a particular resource. In general, this is 
synonymous with the connotation of the word class in object-oriented 
architectures. For VISA Instrument Control Resource Classes, this refers 
to the definition for how to create a resource that controls a particular 
capability of a device. 
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session 

The same as Communication Channel. An instance of a communications 
path between a software element and a resource. Every communication 
channel in VISA is unique. 

SRQ 

IEEE-488 Service Request. This is an asynchronous request (an 
interrupt) from a remote GPIB device that requires service. A service 
request is essentially an interrupt from a remote device. For GPIB, this 
amounts to asserting the SRQ line on the GPIB. For VXI, this amounts 
to sending the Request for Service True event (REQT). 

status byte 

A byte of information returned from a remote device that shows the 
current state and status of the device. If the device follows IEEE-488 
conventions, bit 6 of the status byte indicates if the device is currently 
requesting service. 

template function 

Instrument driver subsystem function common to the majority of 
\IX\plug&play instrument drivers. 

thread 

An operating system object that consists of a flow of control within a 
process. A single process may have multiple threads with each having 
access to the same data space within the process. However, each thread 
has its own stack and all threads may execute concurrently with each 
other (either on multiple processors, or by time-sharing a single 
processor). Note that multi-threaded applications are only supported 
with 32-bit VISA. 

top-level example 

A high-level test-oriented instrument driver function. It is typically 
developed from the instrument driver subsystem functions. 

VISA 

Virtual Instrument Software Architecture. VISA is a common I/O library 
where software from different vendors can run together on the same 
platform. 
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virtual instrument 

A name given to the grouping of software modules (in this case, VISA 
resources with any associated or required hardware) to give the 
functionality of a traditional stand-alone instrument. Within VISA, a 
virtual instrument is the logical grouping of any of the VISA resources. 
The VISA Instrument Control Resources Organizer serves as a means 
to group any number of any type of VISA Instrument Control Resources 
within a VISA system. 

VISA 

Virtual Instrument Software Architecture. This is the general name given 
to this document and its associated architecture. The architecture 
consists of two main VISA components: the VISA Resource Manager 
and the VISA Instrument Control Resources. 

VISA instrument control resources 

This is the name given to the part of VISA that defines all of the device¬ 
specific resource classes. VISA Instrument Control Resources 
encompass all defined device and interface capabilities for direct, low- 
level instrument control. 

VISA resource manager 

This is the name given to the part of VISA that manages resources. This 
management includes support for opening, closing, and finding 
resources, setting attributes, retrieving attributes, and generating events 
on resources, etc. 

VISA Resource Template 

This is the name given to the part of VISA defines the basic constraints 
and interface definition for the creation and use of a VISA resource. All 
VISA resources must derive their interface from the definition of the VISA 
Resource Template. 
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Index 


A 

addressing devices, 44 
addressing device sessions, 44 
Agilent telephone numbers, 16 
Agilent web site, 16 
applications, building, 19 
argument length modifier, 52 
array size, 53 
attributes, 62 

setting VXI trigger lines, 125 
VXI, 123 

B 

BACKPLANE resource class, 409 
buffers, formatted I/O, 57 
building DLLs, 19 

c 

callbacks and events, 62, 69 
closing device sessions, 46 
compiling in HP-UX, 35 
completion codes, 331 
conversion, formatted I/O, 50 
copyright information, 10 

D 

Debug Window, using, 30 
declarations file, 41 
default resource manager, 41 
device sessions 
addressing, 44 
closing, 46 
opening, 42 
directories, VISA, 368 
directory structure, HP-UX, 369 
DLLs, building, 19 


E 

enable events for callback, 72 

enable events for queuing, 78 

error codes, 331, 336 

error messages, logging, 29 

error messages, logging on HP-UX, 35 

event handler, 71 

Event Viewer, using, 29 

events, 62 

callback, 62, 69 
enable for callback, 72 
enable for queuing, 78 
handlers, 62 
hardware triggers, 62 
interrupts, 62 
queuing, 62, 77 
SRQs, 62 
wait on event, 78 
examples 

Checking for VI_SUCCESS, 82 
Checking Instrument Errors, 83 
Determining Window Mapping, 124 
Enable Hardware Trigger Event, 72, 78 
Example Source Code (C/C++), 21 
Example Source Code (HP-UX), 33 
Example Source Code (VB), 26 
Exception Events, 85 
Exclusive Lock, 89 
GPIB (82350) Interface, 97 
GPIB-VXI (E1406A) Interface, 101 
GPIB-VXI (HL) Memory, 105 
GPIB-VXI (LL) Memory, 111 
Installing an Event Handler, 71 
LAN Client (Gateway) Interface, 134 
LAN Client (LAN) Interface, 135 
LAN Server Interface, 140 
LAN Session, 142 
MEMACC Resource Program, 118 
Non-Formatted I/O Functions, 60 
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E (continued) 

examples (cont’d) 

Opening Device Session, 141 
Opening Resource Session, 43 
Opening Session, 46 
Printing Error Code, 82 
Reading a VISA Attribute, 40 
Reading Event Attributes, 69 
Receive Data From Session, 57 
Running Program on HP-UX, 34 
Searching VXI Interface, 48 
Send/Rec Formatted I/O, 58 
SRQ Callback, 74 
Trigger Callback, 73 
Trigger Event Queuing, 79 
Using Array Size Modifier, 53 
Using Callback Method, 70 
Using Field Width Modifier, 51 
Using Precision Modifier, 52 
Using Queuing Method, 77 
Using viPeek16, 109 
VISA LAN Client (Gate), 136 
VISA LAN Client (LAN), 138 
VXI (E8491B) Interfaces, 98 
VXI (High-Level) Memory, 104 
VXI (Low-Level) Memory, 109 
VXI Memory I/O, 114 
Wait on Event for SRQ, 79 

F 

field width, 51 
finding resources, 47 
formatted I/O 

argument length modifier, 52 

array size, 53 

buffers, 57 

conversion, 50 

field width, 51 

functions, 49 

special characters, 53 


F (continued) 

functions 

formatted I/O, 49 
viAssertlntrSignal, 158 
viAssertTrigger, 160 
viAssertUtilSignal, 163 
viBufRead, 165 
viBufWrite, 167 
viClear, 169 
viClose, 171 
viDisableEvent, 173 
viDiscardEvents, 176 
viEnableEvent, 179 
viEventHandler, 183 
viFindNext, 188 
viFindRsrc, 189 
viFlush, 194 
viGetAttribute, 196 
viGpibCommand, 198 
viGpibControlATN, 200 
viGpibControlREN, 202 
viGpibPassControl, 204 
viGpibSendIFC, 206 
viln16, 207 
viln32, 207 
viln8, 207 

vilnstallHandler, 210 
viLock, 212 
viMapAddress, 216 
viMapTrigger, 219 
viMemAlloc, 221 
viMemFree, 223 
viMove, 224 
viMoveAsync, 227 
viMoveln16, 231 
viMoveln32, 231 
viMoveln8, 231 
viMoveOut16, 234 
viMoveOut32, 234 
viMoveOut8, 234 
viOpen, 237 
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F (continued) 

functions (continued) 

viOpenDefaultRM, 241 
viOut16, 243 
viOut32, 243 
viOut8, 243 
viParseRsrc, 246 
viPeek16, 248 
viPeek32, 248 
viPeek8, 248 
viPoke16, 249 
viPoke32, 249 
viPoke8, 249 
viPrintf, 250 
viQueryf, 259 
viRead, 261 
viReadAsync, 264 
viReadSTB, 266 
viReadToFile, 268 
viScanf, 271 
viSetAttribute, 281 
viSetBuf, 283 
viSPrintf, 285 
viSScanf, 287 
viStatusDesc, 289 
viTerminate, 290 
villninstallHandler, 292 
viUnlock, 294 
villnmapAddress, 295 
viUnmapTrigger, 296 
viVPrintf, 298 
viVQueryf, 300 
viVScanf, 302 
viVSPrintf, 304 
viVSScanf, 306 
viVxiCommandQuery, 308 
viWaitOnEvent, 311 
viWrite, 317 
viWriteAsync, 319 
viWriteFromFile, 321 


G 

Glossary, 426 

GPIB Bus Interface resource, 402 
GPIB interface overview, 96 
GPIB-VXI 

attributes, 123 

high-level memory functions, 102 
low-level memory functions, 107 
mapping memory space, 108 
overview, 100 

register programming, 102, 107 
setting trigger lines, 125 
writing to registers, 109 

H 

handlers, 62 
event, 71 
installing, 70 
prototype, 71 

hardware triggers and events, 62 

header file, visa.h, 41 

help 

HyperHelp on HP-UX, 36 
man pages on HP-UX, 36 
high-level memory functions, 102 
HP-UX 

compiling, 35 
directory structure, 369 
linking, 35 

logging messages, 35 
online help, 36 
HyperHelp on HP-UX, 36 

I 

installing handlers, 70 
INSTR resource class, 377 
Instrument Control resource, 377 
interrupts and events, 62 
INTFC resource class, 402 
introducing 10 Libraries, 12 
10 interface, definition, 95 
10 Libraries, introducing, 12 
IP address, 135 
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L 

LAN 

client/server, 129 
GPIB device comm, 141 
hardware architecture, 129 
interfaces overview, 129 
LAN Client, 129, 133 
LAN Server, 129, 140 
signal handling, 145 
software architecture, 131 
timeout values, 143 
timeouts, 143 
VISA LAN Client, 136 
libraries, 19 
linking, in HP-UX, 35 
linking to VISA libraries, 19 
locks, using, 87 
logging error messages, 29 
low-level memory functions, 107 

M 

man pages on HP-UX, 36 
MEMACC 

attribute descriptions, 120 
resource class, 117, 395 
memory functions, 102, 107 
memory I/O performance, 112 
memory I/O services, 117 
memory mapping, 108 
memory space, unmapping, 109 
Message Viewer, using, 29 

N 

non-formatted I/O, 59 

o 

online help, HP-UX, 36 
opening sessions, 41 


P 

printing history, 10 

Q 

queuing and events, 62, 77 

R 

raw I/O, 59 
register programming 

high-level memory, 102 
low-level memory, 107 
mapping memory space, 108 
resource classes, 39, 375 
resource manager session, 41 
resources 
finding, 47 

GPIB Bus Interface, 402 
Instrument Control, 377 
locking, 87 
MEMACC, 117 
Memory Access, 395 
Servant Device-Side, 413 
TCPIP Socket, 420 
VXI Mainframe Backplane, 409 
restricted rights, 9 

s 

searching for resources, 47 
SERVANT resource class, 413 
sessions 

device, 42 
opening, 41 
resource manager, 41 
SICL-LAN protocol, 132 
signal handling with LAN, 145 
SOCKET resource class, 420 
special characters, 53 
SRQs, 62 

starting the resource manager, 41 
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T 

TCP/IP instrument protocol, 132 
TCPIP Socket resource, 420 
telephone numbers, Agilent, 16 
timeouts, LAN, 143 
trademark information, 10 
trigger lines, 125 
triggers and events, 62 
types, VISA, 325 

u 

unmapping memory space, 109 
using the Debug Window, 30 
using the Event Viewer, 29 
using the Message Viewer, 29 

V 

viAssertlntrSignal, 158 
viAssertTrigger, 160 
viAssertUtilSignal, 163 
viBufRead, 165 
viBufWrite, 167 
viClear, 169 
viClose, 171 
viDisableEvent, 173 
viDiscardEvents, 176 
viEnableEvent, 179 
viEventHandler, 183 
viFindNext, 188 
viFindRsrc, 189 
viFlush, 194 
viGetAttribute, 196 
viGpibCommand, 198 
viGpibControlATN, 200 
viGpibControlREN, 202 
viGpibPassControl, 204 
viGpibSendIFC, 206 
vilnl6, 207 
viln32, 207 
viln8, 207 

vilnstallHandler, 210 
viLock, 212 
viMapAddress, 216 


V (continued) 

viMapTrigger, 219 
viMemAlloc, 221 
viMemFree, 223 
viMove, 224 
viMoveAsync, 227 
viMoveln16, 231 
viMoveln32, 231 
viMoveln8, 231 
viMoveOut16, 234 
viMoveOut32, 234 
viMoveOut8, 234 
viOpen, 237 
viOpenDefaultRM, 241 
viOut16, 243 
viOut32, 243 
viOut8, 243 
viParseRsrc, 246 
viPeek16, 248 
viPeek32, 248 
viPeek8, 248 
viPoke16, 249 
viPoke32, 249 
viPoke8, 249 
viPrintf, 250 
viQueryf, 259 
viRead, 261 
viReadAsync, 264 
viReadSTB, 266 
viReadToFile, 268 
VISA 

completion codes, 331 
description, 15 
directories information, 368 
documentation, 16 
error codes, 331, 336 
functions, 149 
resource classes, 39 
support, 15 
types, 325 
users, 15 

visa.h header file, 41 
viScanf, 271 
viSetAttribute, 281 
viSetBuf, 283 
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viSPrintf, 285 
viSScanf, 287 
viStatusDesc, 289 
viTerminate, 290 
viUninstallHandler, 292 
villnlock, 294 
viUnmapAddress, 295 
villnmapTrigger, 296 
viVPrintf, 298 
viVQueryf, 300 
viVScanf, 302 
viVSPrintf, 304 
viVSScanf, 306 
viVxiCommandQuery, 308 
viWaitOnEvent, 311 
viWrite, 317 
viWriteAsync, 319 
viWriteFromFile, 321 
VXI 

attributes, 123 
device types, 95 

high-level memory, 102 
interface overview, 98 
low-level memory, 107 
mapping memory space, 108 
MF Backplane resource, 409 
performance, 112 
register programming, 102, 107 
setting trigger lines, 125 
writing to registers, 109 
VXI-11 protocol, 132 

w 

wait on event, 78 
warranty, 9 
web site, Agilent, 16 
windows 

building applications, 19 
building DLLs, 19 
linking to VISA libraries, 19 
writing to VXI registers, 109 
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